225 lines
16 KiB
Markdown
225 lines
16 KiB
Markdown
# Comprehension history
|
|
|
|
## 2026-10-31T00:16:02Z, PR #181 at 56ff987, against eed1050
|
|
|
|
Ruling: better
|
|
|
|
| Seat | Navigation | Locality | Shape | Self-sufficiency | Overall |
|
|
|---|---|---|---|---|---|
|
|
| Mid A | same | better | same | better | better |
|
|
| Inherited architect | same | better | same | better | better |
|
|
|
|
Mid A, decided by:
|
|
|
|
- Self-sufficiency, Locality: `public/css/styles.css:24` `:root`: the comment above the hex palette says why a colour must not be oklch(), where a colour is edited
|
|
- Locality: `src/ui/stylesheet-floor.test.ts:11` `declares no oklch() colour`: a colour edit that breaks the browser floor fails a test instead of an old engine
|
|
|
|
Inherited architect, decided by:
|
|
|
|
- Self-sufficiency, Locality: `public/css/styles.css:24` `:root`: the comment above the hex palette says why a colour must not be oklch(), where a colour is edited
|
|
- Locality: `src/ui/stylesheet-floor.test.ts:11` `declares no oklch() colour`: a red gate explains the symptom in the file it lands on
|
|
- Self-sufficiency: `README.md:1027` "Two browser floors": the colour rule now sits beside the floor rule
|
|
|
|
## 2026-10-31T00:43:19Z, PR #182 at 19987ba, against 3e70768
|
|
|
|
Ruling: better
|
|
|
|
| Seat | Navigation | Locality | Shape | Self-sufficiency | Overall |
|
|
|---|---|---|---|---|---|
|
|
| Mid A | better | better | better | better | better |
|
|
| Inherited architect | better | better | better | better | better |
|
|
|
|
Mid A, decided by:
|
|
|
|
- Navigation, Shape, Self-sufficiency, Overall: `public/css/auth.css:1` `auth.css`: about 120 lines of rules for markup no view renders are gone, so a cold reader no longer rules them out first
|
|
- Locality, Self-sufficiency, Overall: `public/css/styles.css:31` `--on-accent`: the text colour on the accent is one token where four hard-coded `#fff` stood
|
|
- Self-sufficiency, Navigation, Overall: `public/css/styles.css:287` `@supports not selector(:has(a))`: the nav comment, the partial's header and the rule all say the tree folds only where `:has()` works
|
|
- Locality: `public/css/styles.css:241` `@supports selector(:has(a))`: the nav-fold behaviour now sits in two blocks about 50 lines apart, the second order-dependent; the comment names it
|
|
|
|
Inherited architect, decided by:
|
|
|
|
- Navigation, Shape, Overall: `public/css/auth.css:1` `auth.css`: the false `:target` banner and the phantom state machine are gone, so every selector left names something a view emits
|
|
- Self-sufficiency, Overall: `views/partials/nav-tree.ejs:4` `nav-tree.ejs`: the header and `public/css/styles.css:194` now say the branch folds only where `:has()` works; the old text was untrue on old engines
|
|
- Locality, Overall: `public/css/styles.css:31` `--l-on-accent`: one token feeds `.btn-primary`, `.page-btn[aria-current]` and `.brand-mark`
|
|
- Locality: `public/css/styles.css:287` `@supports not selector(:has(a))`: its `.nav-disc` rule sits about 85 lines from the nav rules it overrides, and `stylesheet-floor.test.ts` guards the order for `.theme-switch` only
|
|
- Self-sufficiency: `src/ui/stylesheet-contrast.test.ts:29` `stylesheet-contrast.test.ts`: the darker badge colours now have a stated 4.5:1 reason someone can find
|
|
|
|
## 2026-10-31T01:09:38Z, PR #183 at 0f20b38, against 364b047
|
|
|
|
Ruling: better
|
|
|
|
| Seat | Navigation | Locality | Shape | Self-sufficiency | Overall |
|
|
|---|---|---|---|---|---|
|
|
| Mid A | same | same | same | better | better |
|
|
| Inherited architect | same | better | same | better | better |
|
|
|
|
Mid A, decided by:
|
|
|
|
- Self-sufficiency, Overall: `public/css/styles.css:1` `App Shell Template header`: the false `light-dark()` bullet is gone, so no reader has to work out which of two comments is lying
|
|
- Self-sufficiency, Overall: `public/css/styles.css:687` `@supports selector(:has(a))` in `@media (max-width: 860px)`: the guard and its comment say what an engine without `:has()` gets, without opening the CHANGELOG
|
|
|
|
Inherited architect, decided by:
|
|
|
|
- Self-sufficiency, Overall: `public/css/styles.css:5` `Architecture` header: the false `light-dark()` bullet is gone, so the header no longer contradicts the TOKENS comment
|
|
- Locality, Self-sufficiency, Overall: `public/css/styles.css:687` `@supports selector(:has(a))` in `@media (max-width: 860px)`: the guard and its comment put the dependency of the open state on `:has()` where an editor would change it
|
|
|
|
## 2026-10-31T01:19:49Z, PR #184 at af157c9, against bb8e6bc
|
|
|
|
Ruling: better
|
|
|
|
| Seat | Navigation | Locality | Shape | Self-sufficiency | Overall |
|
|
|---|---|---|---|---|---|
|
|
| Mid A | better | same | same | better | better |
|
|
| Inherited architect | better | better | same | better | better |
|
|
|
|
Mid A, decided by:
|
|
|
|
- Self-sufficiency, Navigation, Overall: `public/css/styles.css:12` `TOKENS` header comment: says all three theme rules need `:has()`, names the engines without it and points to the `@supports not selector(:has(a))` block, where the old text called the swaps "rock-solid"
|
|
- Navigation, Self-sufficiency, Overall: `README.md:214` `## Glossary`: defines host, plugin, manifest, chrome, nav fragment, permission name, system plugin and denylist and links each to its home section
|
|
- Self-sufficiency: `README.md:815` `Plugin dependencies`: the scale bullet states the plugin count the per-plugin dependency design assumes
|
|
|
|
Inherited architect, decided by:
|
|
|
|
- Self-sufficiency, Locality, Overall: `public/css/styles.css:12` `1. TOKENS` comment: an editor of the theme mapping learns of the distant `:has()` fallback from the comment, where the old text said the swap could not fail
|
|
- Navigation, Self-sufficiency, Overall: `README.md:214` `## Glossary`: a cold reader reaches "chrome" or "denylist" and their home sections in one hop
|
|
- Self-sufficiency: `README.md:815` `### Plugin dependencies`: the scale bullet gives the plugin count the dependency design assumes
|
|
|
|
## 2026-10-31T07:26:19Z, PR #187 at 10152d2, against b336dee
|
|
|
|
Ruling: better
|
|
|
|
| Seat | Navigation | Locality | Shape | Self-sufficiency | Overall |
|
|
|---|---|---|---|---|---|
|
|
| Mid A | same | same | better | better | better |
|
|
| Inherited architect | same | same | better | better | better |
|
|
|
|
Mid A, decided by:
|
|
|
|
- Self-sufficiency, Overall: `e2e-tests/mock-oidc.ts:18` `idToken`: the helpers' signatures now say what `res`, `nonce` and the `codes` map hold
|
|
- Self-sufficiency: `e2e-tests/proxy.ts:14` `toKratos`: `(path: string): boolean` shows the routing predicate's contract
|
|
- Self-sufficiency: `e2e-tests/tsconfig.json:2` `extends`: the specs are held to the host's strict flags, and the Dockerfile comment explains the path link
|
|
- Shape, Overall: `src/ui/icons.ts:4` `ICON_NAMES`: the comment "the icons the UI actually references" is true again
|
|
|
|
Inherited architect, decided by:
|
|
|
|
- Self-sufficiency, Overall: `e2e-tests/mock-oidc.ts:18` `b64`: typed helpers replace a trace through the `createServer` callback
|
|
- Self-sufficiency: `e2e-tests/proxy.ts:14` `toKratos`: the predicate's contract is readable on its own line
|
|
- Self-sufficiency: `e2e-tests/Dockerfile:11` `COPY tsconfig.json`: the relative `extends` path works in the checkout and in the image, and a comment names the link
|
|
- Shape, Overall: `src/ui/icons.ts:4` `ICON_NAMES`: the registry matches its description, with no dead ids
|
|
|
|
## 2026-10-31T12:28:23Z, PR #200 at 3592a30, against a8a9744
|
|
|
|
Ruling: same
|
|
|
|
| Seat | Navigation | Locality | Shape | Self-sufficiency | Overall |
|
|
|---|---|---|---|---|---|
|
|
| Mid A | better | better | better | same | better |
|
|
| Inherited architect | worse | worse | better | same | same |
|
|
| Maintainability senior | same | same | better | same | same |
|
|
| Junior A | better | better | better | better | better |
|
|
|
|
Mid A, decided by:
|
|
|
|
- Navigation, Locality, Shape: `src/ui/chrome.ts:74` `shellUser`: the deleted `buildShellContext` and `buildDashboardModel` left two shell models side by side, and now every page reads one `chrome`
|
|
- Locality, Shape: `src/auth/routes.ts:58` `flowFailure`: a named unit shared by `flowPage` and `codeFlowSubmit`, where the old `flowPage` held the whole error ladder inline
|
|
- Shape: `src/auth/kratos-public.ts:117` `submitFlow`: takes a flow type and id instead of an action URL, and the Referer quirk is explained where it applies
|
|
- Locality: `src/http/static.ts:93` `versioned`: reads the module-level `hashes` map, so an asset href depends on what an earlier request hashed
|
|
- Navigation, Shape: `src/ui/stylesheet-floor.ts:30` `floorViolations`: a 249-line regex walker that only tests use sits in `src/ui/` beside runtime modules, though the README now points straight at it
|
|
|
|
Inherited architect, decided by:
|
|
|
|
- Navigation: `public/css/styles.css:25` `:root`: the old comment next to the palette answered the 3am question and the new text drops it
|
|
- Navigation: `src/ui/stylesheet-floor.ts:1` `floorViolations`: its header never says an unsupported value in a custom property blanks every `var()` reading it, so a cold reader walks the regex walker to find the cause
|
|
- Navigation, Shape: `src/ui/stylesheet-floor.ts:12` `import`: test-only tooling that pulls a devDependency sits beside runtime modules and is missing from the README file map
|
|
- Locality: `src/http/static.ts:64` `hashes`: a module-level map shared by every `publicAssets()` instance makes a fresh href depend on request history elsewhere
|
|
- Locality: `src/http/app.ts:188` `renderPage`: `assetHref` is appended last at three render sites, and only a comment keeps a fourth from emitting unversioned hrefs
|
|
- Shape: `src/ui/chrome.ts:74` `shellUser`: removes the second shell model that duplicated `PageChrome`
|
|
- Shape: `src/auth/routes.ts:58` `flowFailure`: one named unit shared by `flowPage` and `codeFlowSubmit`, each handler reads in a screen
|
|
|
|
Maintainability senior, decided by:
|
|
|
|
- Shape, Locality: `src/ui/chrome.ts:74` `shellUser`: the deleted `ShellModel` left two shapes for the same chrome, and now the shell has one input and one builder
|
|
- Shape, Locality: `src/auth/routes.ts:58` `flowFailure`: the old `flowPage` mixed about 60 lines of error mapping with `return_to` handling, and now `flowReturnTo` and `flowFailure` read on their own
|
|
- Locality: `src/http/static.ts:64` `hashes`: a hidden module-level cache filled by two readers, and `assetHref` is merged by hand at three render sites
|
|
- Shape, Navigation: `src/ui/stylesheet-floor.ts:119` `positive`: a 249-line regex walker that only a test uses sits among runtime view modules
|
|
|
|
Junior A, decided by:
|
|
|
|
- Navigation, Self-sufficiency: `src/ui/stylesheet-floor.ts:1` `floorViolations`: the README's "Two browser floors" points here and the header lists what is checked, where the base had a prose rule and a hand-written regex test
|
|
- Shape, Locality: `src/ui/chrome.ts:74` `shellUser`: one shell view model replaces `ShellModel` beside `PageChrome`, and its helpers sit beside their only caller
|
|
- Shape, Locality: `src/auth/routes.ts:58` `flowFailure`: named units replace about 60 inline lines in `flowPage`, and `codeFlowSubmit` reuses them
|
|
- Self-sufficiency: `src/auth/kratos-admin.ts:68` `createRecoveryCode`: the comment no longer claims Kratos mails the link
|
|
- Locality: `src/http/static.ts:64` `hashes`: a module-level mutable map backs asset versioning, hidden state the base didn't have
|
|
|
|
## 2026-10-31T12:30:19Z, PR #200 at 3592a30
|
|
|
|
| Seat | Navigation | Locality | Shape | Self-sufficiency | Overall |
|
|
|---|---|---|---|---|---|
|
|
| Junior A | 7 | 6 | 6.5 | 6.5 | 6.5 |
|
|
| Mid A | 7 | 6 | 6.5 | 6.5 | 6.5 |
|
|
| Maintainability senior | 7 | 6 | 6.5 | 6.5 | 6.5 |
|
|
| Inherited architect | 7 | 5.5 | 5.5 | 7.5 | 6.5 |
|
|
| Mean | 7.00 | 5.88 | 6.25 | 6.75 | 6.50 |
|
|
|
|
Junior A, hardest first:
|
|
|
|
- Locality, Overall: `src/ui/stylesheet-floor.ts:119` `positive`: a regex-built `@supports` evaluator whose header says what it enforces but not how it decides a guard names a feature
|
|
- Locality, Overall: `src/http/app.ts:185` `handleRequest`: about 165 lines in one closure where each stage reads state an earlier stage set
|
|
- Self-sufficiency: `src/auth/routes.ts:58` `flowFailure`: its 4xx branches can't fire from `codeFlowSubmit` because `submitFlow` throws only on 5xx, and the call site doesn't say so
|
|
|
|
Mid A, hardest first:
|
|
|
|
- Locality, Overall: `src/ui/stylesheet-floor.ts:119` `positive`: a hand-written CSS walker with three regex passes per declaration, opaque at line level
|
|
- Locality, Overall: `src/http/app.ts:185` `handleRequest`: a fixed order of about 15 stages that nothing in the code enforces
|
|
- Self-sufficiency, Shape: `src/auth/login.ts:40` `readPermissions`: the comment names the tuple `#members` where the code uses `granted`
|
|
- Locality: `src/auth/routes.ts:121` `codeFlowSubmit`: one idea split across `flow-view.ts`, `routes.ts` and `kratos-public.ts`
|
|
|
|
Maintainability senior, hardest first:
|
|
|
|
- Locality, Overall: `src/http/app.ts:185` `handleRequest`: a 167-line closure of complexity 43 whose order across closure state nothing names as a contract
|
|
- Self-sufficiency, Locality: `src/auth/routes.ts:58` `flowFailure`: on the submit path every 4xx branch is dead and nothing at the call site says which can fire
|
|
- Locality: `src/ui/stylesheet-floor.ts:119` `positive`: the one module whose correctness can't be checked by reading
|
|
- Self-sufficiency: `src/auth/bootstrap.ts:31` `permissionTuple`: the comment says `#members` while the code writes `granted`
|
|
|
|
Inherited architect, would restructure first:
|
|
|
|
- Shape, Navigation: `src/auth/flow-view.ts:152` `formAction`: the flow-to-route mapping has two homes, here and `routes.ts`, so a code flow's route and its form target are decided in different files
|
|
- Shape, Navigation: `src/ui/stylesheet-floor.ts:30` `floorViolations`: a CSS linter that never runs at runtime sits among the runtime view helpers
|
|
- Locality, Shape: `src/http/app.ts:185` `handleRequest`: a level of its own inside `createApp`
|
|
- Shape: `src/http/builtin-routes.ts:23` `matchBuiltinRoute`: holds no routes, because the table is inline in `app.ts:176` and `buildAuthRoutes`
|
|
|
|
## 2026-10-31T12:30:27Z, PR #200 rerun at 3592a30
|
|
|
|
| Seat | Navigation | Locality | Shape | Self-sufficiency | Overall |
|
|
|---|---|---|---|---|---|
|
|
| Junior A | 7 | 5.5 | 6 | 6.5 | 6 |
|
|
| Mid A | 7 | 6 | 6.5 | 6.5 | 6.5 |
|
|
| Maintainability senior | 7 | 5.5 | 6 | 6.5 | 6 |
|
|
| Inherited architect | 7 | 6 | 6 | 6.5 | 6.5 |
|
|
| Mean | 7.00 | 5.75 | 6.13 | 6.50 | 6.25 |
|
|
|
|
Junior A, hardest first:
|
|
|
|
- Locality, Overall: `src/ui/stylesheet-floor.ts:119` `positive`: a regex-built CSS walker that stayed opaque without tracing it by hand
|
|
- Locality, Overall: `src/http/app.ts:185` `handleRequest`: about 320 lines of interdependent locals, with a fixed stage order that only a top-to-bottom read shows
|
|
- Self-sufficiency, Shape: `src/auth/login.ts:40` `completeLogin`: the header says `#members` where the code uses `granted`
|
|
|
|
Mid A, hardest first:
|
|
|
|
- Locality, Overall: `src/http/app.ts:185` `handleRequest`: about 165 lines of order-dependent stages, with `renderPage` reassigned partway
|
|
- Locality, Overall: `src/ui/stylesheet-floor.ts:119` `positive`: how it decides a guard names a feature stayed opaque
|
|
- Self-sufficiency, Shape: `src/auth/bootstrap.ts:31` `seedPermissions`: the comment says `#members` where the code uses `granted`
|
|
|
|
Maintainability senior, hardest first:
|
|
|
|
- Locality, Overall: `src/http/app.ts:185` `handleRequest`: about 167 lines and complexity 43 in a fixed order nobody states
|
|
- Locality, Overall: `src/ui/stylesheet-floor.ts:119` `positive`: a hand-rolled regex CSS walker, partly opaque
|
|
- Locality, Shape: `src/plugin-host/plugin.ts:126` `RESERVED_PLUGIN_IDS`: a hand-kept mirror of the host's path segments that has already drifted, as it omits `error`
|
|
- Self-sufficiency, Shape: `src/auth/login.ts:40` `readPermissions`: the comment says `#members` where the code uses `granted`
|
|
|
|
Inherited architect, would restructure first:
|
|
|
|
- Locality, Overall: `src/http/app.ts:185` `handleRequest`: the most concerns and the highest complexity, already grandfathered, and every request-wide concern lands in it
|
|
- Shape, Navigation: `src/ui/stylesheet-floor.ts:15` `FLOOR`: the 3am rule's home is a test-only module under `ui/`
|
|
- Shape: `src/auth/routes.ts:275` `buildAuthRoutes`: the 19-module `src/auth/` mixes six concerns, and this file with `flow-view.ts` is where the next flow lands
|