TODO

# TODO List for html-theme-ref

This is a poor-man's issue tracker. I am not primarily a GitHub user so don't
want to commit to their issue tracking feature, but my primary SVC service
provider (Bitbucket) only offers paid integration into their issue tracker
(Jira). I don't have the time (and patience) at the moment to analyze the best
approach, so this file will have to suffice.

It's a very simple concept: Track any issues (features, bugfixes, hotfixes) in
here, assign a sequential number to it and use that number when branching.

I will try to develop a format so that I can parse the file later on, should I
decide to migrate to a real issue tracker. It's probably going to be Bugzilla,
but for that my html-theme-ref project needs to stabilize first.

## Format Specification

The file uses Markdown conventions for formatting headers and other text block
entitities, but SHOULD NOT be considered a Markdown file. That's why it has no
definitive file extension.

Each issue entry follows a structured format for easier parsing and future
migration.  Issues MUST be **appended** to this file and never moved, to
preserve Git diffing.

### Issue Format

```

ID: [ISSUE-NUMBER]
Type: [feature/bugfix/hotfix]
Title: [Short title]
Status: [open/in-progress/done/hold/cancelled]
Priority: [low/medium/high]
Created: [YYYY-MM-DD]
Description: [Detailed explanation]

---
```

- ISSUE-NUMBERs must be sequential
- truncation of description must be indentended so that every line starts at the
  same column
- issues must be started with two LF
- issues must be terminated with two LF, then `---`
- issues may have a free-text field (epilog), which must be started with two LF.

## Issues

ID: 1
Type: feature
Title: Node.js | html-webpack-plugin - using wrong webpack hooks
Status: open
Priority: low
Created: 2025-04-21
Description: - affects `webpack-dev-server`
             - results in changes applied to watched files not emitting updated
               outputs
             - likely an issue with incorrect usage of hooks for proper cache
               handling
             - suggested workaround did not work
             - [remediated](https://github.com/ByteB4rb1e/html-theme-ref/blob/7c15371f6ab72bb1dd69388888d0d8beffc65082/webpack.config.doc.js#L465)
               by instructing `webpack-dev-middleware` to write to disk, instead
               of handling changes solely in memory. This was my intended
               behavior anyway...

https://github.com/jantimon/html-webpack-plugin/issues/1768
---

ID: 2
Type: bugfix
Title: Node.js | ts-node - unable to correctly parse with ESM options
Status: open
Priority: medium
Created: 2025-04-21
Description: - affects `npx ts-node scripts/*.ts`
             - results in scripts not being executed with error `TypeError
               [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".ts" for
               ...`, if `type` in package.json is set to `module`.
             - suggested workaround does not work
             - (accidentally)
               [remediated](https://github.com/ByteB4rb1e/html-theme-ref/blob/4a2344e7f1a278063527bbeb2a2ef5281498b633/package.json#L9)
               by setting `type` in `package.json` to `commonjs`. This is
               contradictory to the entire build environment being authored as
               ESM, but since I'm explicitly defining each module as an ESM
               module through the `.mjs` extension name (you've been hit by,
               you've been struck by a smooooth criminal 🕺), [this will
               override the default
               behavior](https://nodejs.org/download/release/v18.20.8/docs/api/modules.html#enabling)
               of the `package.json`

https://github.com/TypeStrong/ts-node/issues/2122
---

ID: 3
Type: bugfix
Title: Node.js | jest - deprecated dependencies
Status: open
Priority: high
Created: 2025-04-21
Description: - affects `npm install`.
             - results in deprecation notice during `npm install`.
             - [remediated](https://github.com/ByteB4rb1e/html-theme-ref/blob/cb642ec72b4488ddfc8dfb63fe977e85d9c28506/package.json#L35)
               by adding override in `package.json` for upgrading child
               dependencies.
             - i will ditch `jest` altogether as I don't see behavior-driven
               development/testing fitting for the project. I've tested quite a
               few testing frameworks in the Javascript ecosystem and none
               really satisfied my expectations. I'm looking for a
               straightforward Beck/xUnit framework, which must at least be
               authored in ESM6 to utilizie object-orientation for synatactial
               structure. All the JavaScript testing frameworks I came across
               all use the "workaround" syntax that was established because of
               CommonJS. I will implement my own test runner for this as I don't
               require more than runners, suites, cases, fixtures and
               assertions. I treat DOM objects as I would treat any other
               fixture, so don't (yet) see any reason why that shouldn't also
               suffice for browser testing...

https://github.com/jestjs/jest/issues/15503

---

ID: 4
Type: bugfix
Title: error when uploading Bitbucket download artifacts
Status: in-progress
Priority: high
Created: 2025-05-08
Description: when uploading the distribution via
             `scripts/bitbucket-cloud-upload.ts`, the upload works and is shown
             in Bitbucket Cloud, but the data is scrambled. Not even the magic
             byte of the gzipped tarball is correct. I suspect this has
             something to do with the buffering of the Node.js http module, but
             am not sure. It might make sense to test this with the streaming
             function of the module, instead of taking care of buffering myself.
             Though this MUST only be for testing purposes. I refuse to accept
             that manual buffer handling isn't working in connection with the
             module. I'm currently creating a debugging server so that I can
             inspect the transmission in detail. It's a little involved, as
             other things like HTTP chunking come into play... See
             https://bitbucket.org/byteb4rb1e/py-utils, for more information.
             Yes, I could just resort to using curl, but the whole point of the
             script is not to have any dependencies outside of the Node.js
             ecosystem. It also turned out to be a very good exercise debugging
             all of this.

---

ID: 5
Type: feature
Title: remove Makefile watch target in favor of build option
Status: in-progress
Priority: low
Created: 2025-05-08
Description: There currently is an explicit target for watching the build. This
             is redundant and should be an option for the targets where it
             applies instead. E.g. `build/debug` should have an option for
             watching, as should `uat`, so that `make build/debug WATCH=1` is
             possible.

---

ID: 6
Type: feature
Title: DIN 5001 letter document
Status: in-progress
Priority: low
Created: 2025-06-06
Description: document abstraction for relatively positioned documents of
             standardized German letter format DIN 5008

---

ID: 7
Type: feature
Title: Implement Sea Harvest Clone
Status: in-progress
Priority: high
Created: 2025-06-07
Description: I've decided on cloning an existing HTML theme instead of coming up
             with my own, or keeping everything plain. I've tended towards
             keeping it plain, to emphasize my focus on explicit functionality
             rather than design. But good design in itself is functional so I'd
             rather clone a well-designed theme as a starter to have more time
             to focus on real functionality. I've stumbled upon the Sea Harvest
             Australia web site, which, in my eyes, is well-designed.

---

ID: 8
Type: feature
Title: Rework build system interface and packaging
Status: done
Priority: high
Created: 2025-06-11
Description: Standardize packaging and remove abstractions from build interface.
             Also, add workaround for issue 4 to allow for publishing archives
             immediately.

---