kayg/calternal

Watch

Fork 0

DOCS: add module and API notes and refresh app comment references #900

New issue

Open

opened 2026-10-02 17:38:26 +00:00 by kayg · 2 comments

kayg commented

2026-10-02 17:38:26 +00:00

Owner

Evidence

At the #863 audit base, the file-header scan found 211 files in apps/web/src without a leading module comment (tests are included in this count). Examples are lib/selectionContextBar.ts:1, lib/auth/passkeys.ts:1, and lib/editor/blockMenu.ts:1.
A case-sensitive scan for common third-party names found 207 comment lines in 82 files. Examples: lib/platform.ts:4 names Safari and Firefox; lib/appearance/readability.ts:143 names Unsplash.
Non-obvious exported functions without a function comment include lib/auth/passkeys.ts:30 (authPost), :110 (registerPasskey), :126 (signInWithPasskey), and routes/settings/api.svelte.ts:23 (withStepUp).
The app stylesheet is calternal-app.css. However, lib/styles/auth-ui.css:18 says it is imported from app.css; the import is at calternal-app.css:16. lib/styles/scrim.css:11 also points to app.css :root; the app token values are in calternal-app.css:397-400. Comments also point to local .superpowers/sdd/ documents that are not tracked.

Owner rule

Comments are documentation. Each module and each non-obvious function needs a short, current comment. Source comments must not name third-party products.

Expected behaviour

Add module comments where missing. Explain the non-obvious passkey and step-up request invariants. Replace product names with protocol or behaviour descriptions. Use the current stylesheet path, or state clearly when a reference means the upstream source. Replace local-only research paths with the decision and evidence needed in the comment itself. Keep behavior unchanged.

Test idea

Run a source scan for module/function comments and third-party names. Review every changed reference against the current import graph. Keep the existing passkey and Settings API tests unchanged.

## Evidence At the #863 audit base, the file-header scan found 211 files in `apps/web/src` without a leading module comment (tests are included in this count). Examples are `lib/selectionContextBar.ts:1`, `lib/auth/passkeys.ts:1`, and `lib/editor/blockMenu.ts:1`. A case-sensitive scan for common third-party names found 207 comment lines in 82 files. Examples: `lib/platform.ts:4` names Safari and Firefox; `lib/appearance/readability.ts:143` names Unsplash. Non-obvious exported functions without a function comment include `lib/auth/passkeys.ts:30` (`authPost`), `:110` (`registerPasskey`), `:126` (`signInWithPasskey`), and `routes/settings/api.svelte.ts:23` (`withStepUp`). The app stylesheet is `calternal-app.css`. However, `lib/styles/auth-ui.css:18` says it is imported from `app.css`; the import is at `calternal-app.css:16`. `lib/styles/scrim.css:11` also points to `app.css :root`; the app token values are in `calternal-app.css:397-400`. Comments also point to local `.superpowers/sdd/` documents that are not tracked. ## Owner rule Comments are documentation. Each module and each non-obvious function needs a short, current comment. Source comments must not name third-party products. ## Expected behaviour Add module comments where missing. Explain the non-obvious passkey and step-up request invariants. Replace product names with protocol or behaviour descriptions. Use the current stylesheet path, or state clearly when a reference means the upstream source. Replace local-only research paths with the decision and evidence needed in the comment itself. Keep behavior unchanged. ## Test idea Run a source scan for module/function comments and third-party names. Review every changed reference against the current import graph. Keep the existing passkey and Settings API tests unchanged.

kayg referenced this issue

2026-10-02 17:44:36 +00:00

Audit: module docs and stale comments (comments are docs) #863

kayg commented

2026-10-02 18:09:31 +00:00

Author

Owner

Final comment-only commit for #900: fe9381d206e0a52cd2b5e58a4b11085446f776e4 (supersedes the intermediate SHA above). The branch also contains the requested origin/dev update; final head a82305864d94a3194015404b6deddbb366ab55b1.

Source comparison: executable source and test directives are unchanged across all 409 files. All 246 audit-listed modules have leading comments.

Final gates: cargo fmt --check exited 0 with no stdout or stderr. The combined bunx prettier --check exited 1:

[warn] Code style issues found in 405 files. Run Prettier with --write to fix.

The same 405 files fail the same formatter on origin/dev; there are zero new formatting failures. No code formatting changed. Full gate output and file inventory are in the final #863 report. No builds or runtime tests run, as required by this job. This issue remains open.

Final comment-only commit for #900: `fe9381d206e0a52cd2b5e58a4b11085446f776e4` (supersedes the intermediate SHA above). The branch also contains the requested `origin/dev` update; final head `a82305864d94a3194015404b6deddbb366ab55b1`. Source comparison: executable source and test directives are unchanged across all 409 files. All 246 audit-listed modules have leading comments. Final gates: `cargo fmt --check` exited 0 with no stdout or stderr. The combined `bunx prettier --check` exited 1: ```text [warn] Code style issues found in 405 files. Run Prettier with --write to fix. ``` The same 405 files fail the same formatter on `origin/dev`; there are zero new formatting failures. No code formatting changed. Full gate output and file inventory are in the final #863 report. No builds or runtime tests run, as required by this job. This issue remains open.

kayg referenced this issue

2026-10-02 18:09:58 +00:00

Audit: module docs and stale comments (comments are docs) #863

kayg referenced this issue from a commit

2026-10-02 18:10:51 +00:00

docs(web): document module roles and current auth and focus rules (#900)

kayg commented

2026-10-03 00:35:36 +00:00

Author

Owner

Repair on job/docsfix-web (not pushed): bf5d2643f docs(web): restore platform, browser and library names in comments.

Clarified rule (owner, 2026-10-02): do not name competing apps (other notes, calendar, mail or photo apps) in UI, code or comments. Platform, OS, browser, protocol, client and library names that state technical facts stay.

The name scrub replaced facts with garbled stand-ins in about 750 comment lines: "iOS 26.5" became "touch-platform.5", "Safari 15+" became "the browser 15+", "than the" became "tha". This commit restores:

every platform, browser and client name (iOS, iPadOS, macOS, Safari, WebKit, Chromium, Chrome, Firefox, Finder, Apple Calendar, iPhone, iPad, Android, Windows, Linux);
library names (ProseMirror, TipTap, StarterKit, Yjs, Yrs, jsdom, Sonner, Bklit, Torph, lowlight, highlight.js, pdf.js, hls.js, Svelte, React, Lucide, Playwright);
the focus-ring research references (.superpowers/sdd/focus-ring-research.md, research §0/§1/§5b), whatwg/html#8087 with engine versions, WebKit bug 296492 and the iOS gesture research note;
Claude, Codex and Unsplash in comments, and iCloud, Fastmail and Nextcloud as CalDAV servers in the Calendars header.

Kept: the new module headers, the app.css → calternal-app.css path fixes, the #611 motion notes and the retired-task cleanup in slash.test.ts. Competing notes, photo and budget apps (Obsidian, Craft, Notion, Fantastical, Immich, Google Photos, Apple Photos, Apple Notes, YNAB) stay unnamed. Their stand-ins now read as plain English (for example "extended-Markdown pipe syntax", "envelope-budget", "common note editors").

Repair on `job/docsfix-web` (not pushed): `bf5d2643f` docs(web): restore platform, browser and library names in comments. Clarified rule (owner, 2026-10-02): do not name competing apps (other notes, calendar, mail or photo apps) in UI, code or comments. Platform, OS, browser, protocol, client and library names that state technical facts stay. The name scrub replaced facts with garbled stand-ins in about 750 comment lines: "iOS 26.5" became "touch-platform.5", "Safari 15+" became "the browser 15+", "than the" became "tha". This commit restores: - every platform, browser and client name (iOS, iPadOS, macOS, Safari, WebKit, Chromium, Chrome, Firefox, Finder, Apple Calendar, iPhone, iPad, Android, Windows, Linux); - library names (ProseMirror, TipTap, StarterKit, Yjs, Yrs, jsdom, Sonner, Bklit, Torph, lowlight, highlight.js, pdf.js, hls.js, Svelte, React, Lucide, Playwright); - the focus-ring research references (`.superpowers/sdd/focus-ring-research.md`, research §0/§1/§5b), whatwg/html#8087 with engine versions, WebKit bug 296492 and the iOS gesture research note; - Claude, Codex and Unsplash in comments, and iCloud, Fastmail and Nextcloud as CalDAV servers in the Calendars header. Kept: the new module headers, the `app.css` → `calternal-app.css` path fixes, the #611 motion notes and the retired-task cleanup in `slash.test.ts`. Competing notes, photo and budget apps (Obsidian, Craft, Notion, Fantastical, Immich, Google Photos, Apple Photos, Apple Notes, YNAB) stay unnamed. Their stand-ins now read as plain English (for example "extended-Markdown pipe syntax", "envelope-budget", "common note editors"). Check: `git diff origin/dev...HEAD | grep '^-' | grep -E 'iOS|macOS|Safari|WebKit|Chrom|Firefox|Apple|Finder|Thunderbird|Android|Windows'` now lists only moved or rewrapped lines and the competing-app lines. Comments only. Prettier is not set up for Svelte in this repo, so I did not run it.

No labels

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

kayg/calternal#900

No description provided.

Rows
Columns