docs: shallow file analysis of `drasil-code` by balacij · Pull Request #5237 · JacquesCarette/Drasil

balacij · 2026-07-02T17:33:59Z

Posting the shallow file analysis of drasil-code.

After #5201, I will break up some of the tangible pieces of work found in this analysis into issues for us to discuss in more detail.

JacquesCarette · 2026-07-02T21:17:57Z

Please make sure to post the other analyses as well (separately). I'll review this one carefully, later.

JacquesCarette

There are more comments and questions than actual "changes requested", but the upshot is the same: needs more before being pulled in.

JacquesCarette · 2026-07-07T00:07:30Z

+
+### `./lib/Language/Drasil/GOOL.hs`
+
+Re-export file.


Should this exist at all?

JacquesCarette · 2026-07-07T00:16:29Z

+
+For example, we can have our own implementation of `sin` or we can use the one from `java.lang.Math`. Currently we lock ourselves into a single `sin` implementation with GOOL, but we should be able to modify this.
+
+In some sense, this has the potential to be one of the most important files in `drasil-code` (if not the most).


But does it belong in drasil-code at all? I agree that this is super useful, but where in our pipeline does it belong?

JacquesCarette · 2026-07-07T00:18:26Z

+
+#### `./lib/Language/Drasil/ICOSolutionSearch.hs`
+
+About solving the execution order for an ICO problem.


Also: does it really belong 'here'?

JacquesCarette · 2026-07-07T00:19:24Z

+This file contains an AST for building modules (heavily OO-inspired class files), objects, and function bodies.
+
+* [ ] This file should not be re-exported through `Language.Drasil.Code` on the basis that it circumvents the normal activities of `drasil-gen`.
+* [ ] The file is very OO-oriented without explicitly noting that. We should make that more clear.


In theory, when this was built, it was meant to be Parnas-style modules, and not directly OO.

JacquesCarette · 2026-07-07T00:22:23Z

+
+### ODEs
+
+I'm going to ask a very silly question: why are ODEs ever related to code generation?!


They are not. They ended up here because we 'generate' calls to ode-solving libraries. So all the stuff about external libraries (for solving ODEs) could belong here indeed. Everything else does not. ODEs are a mathematical domain, and should be treated as such. I would not be surprised if some of the code wanted to be in drasil-theory (for now) instead. Even that will likely want to be split up -- later!

JacquesCarette · 2026-07-07T00:25:06Z

+
+#### Makefile Generation
+
+Both of these files need to be moved to a `Makefile` namespace, preferably within `SoftwareDossier` for now (even though I don't think that will be its final home).


and not drasil-build, whatever it is called now?

JacquesCarette · 2026-07-07T00:26:27Z

+An implementation of a "software dossier" custom to that specific language.
+
+* [ ] Are the monads used anywhere?
+* [ ] The typeclass usage for `SoftwareDossierSym` looks like over-engineering. We should reevaluate the design.


And why are they in drasil-code at all? This is the only place (outside GOOL) where there is knowledge of the target platforms. Feels very anti-modular.

JacquesCarette · 2026-07-07T00:27:59Z

+
+There's so many things that are implicitly assumed here!
+
+1. Why are we assuming that we're going to generate an "input parameters" module? How is that at all relevant to "code"? Reading in values from various sources is sensible, but that's on the level of code blocks. This architectural choice of wrapping all input values (i.e., bundling them) is a choice that should have already been processed. In other words, `InputParameters` should be a module that carries a single function `read_inputs` that does the reading and bundling into a `struct`, but (!), this is a design decision that should have been made earlier.


Right, our own (generated) software architecture choices is deeply embedded in this code.

JacquesCarette · 2026-07-07T00:29:16Z

+data ClassType = Primary | Auxiliary
+```
+
+This file also defines the above datatype for differentiating between a "primary module" from "auxiliary modules." I don't understand the difference between a primary and auxiliary module. From a very quick scan, it looks like what it really wants to establish is the difference between a file containing a program entry point or not.


your guess is correct.

JacquesCarette · 2026-07-07T00:31:02Z

+* [ ] Is the pattern strictly necessary? I think we can simplify it (by removing it).
+* [ ] Investigate: Why `ProgData` and `packageAux`? What does this really capture?
+
+One meta-comment about `drasil-code`: we use too many abbreviations that make the code hard to read.


Could you put a summary of the main findings at the top of the analysis?

JacquesCarette · 2026-07-15T19:18:47Z

This one is still WIP? Awaiting answers on my queries.

docs: old shallow file analysis of `drasil-utils`

balacij requested a review from JacquesCarette as a code owner July 2, 2026 17:33

docs: shallow file analysis of drasil-code

bc2fec6

balacij force-pushed the codeFileAnalysis branch from 493de88 to bc2fec6 Compare July 2, 2026 17:38

balacij mentioned this pull request Jul 4, 2026

docs: shallow file analysis of drasil-makefile #5243

Open

docs: old shallow file analysis of drasil-utils

6f3bc97

balacij mentioned this pull request Jul 4, 2026

docs: old shallow file analysis of drasil-utils #5245

Merged

JacquesCarette requested changes Jul 7, 2026

View reviewed changes

This was referenced Jul 8, 2026

Use more classy lenses in drasil-code #5269

Merged

refactor(SmithEtAlSRS): move to drasil-srs #5287

Merged

Merge pull request #5245 from JacquesCarette/utilsFileAnalysis

6f8ef33

docs: old shallow file analysis of `drasil-utils`


		For example, we can have our own implementation of `sin` or we can use the one from `java.lang.Math`. Currently we lock ourselves into a single `sin` implementation with GOOL, but we should be able to modify this.

		In some sense, this has the potential to be one of the most important files in `drasil-code` (if not the most).


		#### `./lib/Language/Drasil/ICOSolutionSearch.hs`

		About solving the execution order for an ICO problem.


		### ODEs

		I'm going to ask a very silly question: why are ODEs ever related to code generation?!


		#### Makefile Generation

		Both of these files need to be moved to a `Makefile` namespace, preferably within `SoftwareDossier` for now (even though I don't think that will be its final home).


		There's so many things that are implicitly assumed here!

		1. Why are we assuming that we're going to generate an "input parameters" module? How is that at all relevant to "code"? Reading in values from various sources is sensible, but that's on the level of code blocks. This architectural choice of wrapping all input values (i.e., bundling them) is a choice that should have already been processed. In other words, `InputParameters` should be a module that carries a single function `read_inputs` that does the reading and bundling into a `struct`, but (!), this is a design decision that should have been made earlier.

Conversation

balacij commented Jul 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

JacquesCarette commented Jul 2, 2026

Uh oh!

JacquesCarette left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JacquesCarette commented Jul 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

balacij commented Jul 2, 2026 •

edited

Loading