kayg/calternal

Watch

Fork 0

DOCS: add module and anchor API comments in packages/editor #902

New issue

Open

opened 2026-10-02 17:38:30 +00:00 by kayg · 3 comments

kayg commented

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

Owner

Evidence

At the #863 audit base, 16 files in packages/editor/src have no leading module comment. Examples: blockSelection.ts:1, linkCommand.ts:1, and index.ts:1.
A case-sensitive scan found 143 comment lines in 32 files that name common third-party products. For example, noteCardsDecoration.ts:1 calls the card treatment “Craft-style” and names ProseMirror.
Non-obvious exported functions without function comments include anchor.ts:67 (splitTrailingBlockIdForDisplay), :79 (countBlockAnchors), and :249 (trailingBlockAnchorRange). slash.test.ts:1 also points to an untracked .superpowers/sdd/ed-4-brief.md.

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 and document anchor parsing, matching, and display invariants. Describe the card and editor behavior without product names. Replace local-only design-file references with the decision in the source comment. Do not change editor behavior.

Test idea

Run a source scan for module/function comments and product names. Keep the editor serialization and anchor tests unchanged.

## Evidence At the #863 audit base, 16 files in `packages/editor/src` have no leading module comment. Examples: `blockSelection.ts:1`, `linkCommand.ts:1`, and `index.ts:1`. A case-sensitive scan found 143 comment lines in 32 files that name common third-party products. For example, `noteCardsDecoration.ts:1` calls the card treatment “Craft-style” and names ProseMirror. Non-obvious exported functions without function comments include `anchor.ts:67` (`splitTrailingBlockIdForDisplay`), `:79` (`countBlockAnchors`), and `:249` (`trailingBlockAnchorRange`). `slash.test.ts:1` also points to an untracked `.superpowers/sdd/ed-4-brief.md`. ## 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 and document anchor parsing, matching, and display invariants. Describe the card and editor behavior without product names. Replace local-only design-file references with the decision in the source comment. Do not change editor behavior. ## Test idea Run a source scan for module/function comments and product names. Keep the editor serialization and anchor 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 17:57:35 +00:00

Author

Owner

Committed 537cdebe95681c90fb7252e2d123b87216083d85 for #902. Added all 16 audit-listed module headers, documented the display splitter, parsed anchor counts and trailing range coordinates, replaced product comparisons with grammar and behavior descriptions, and replaced the untracked slash research path with the caller-owned command-list invariant. Comment-only source comparison preserves runtime tokens and test directives. No expectations changed.

Prettier check output (exit 1):

Checking formatting...
[warn] packages/editor/src/Editor.svelte
[warn] packages/editor/src/Editor.svelte.test.ts
[warn] packages/editor/src/anchor.test.ts
[warn] packages/editor/src/anchor.ts
[warn] packages/editor/src/attachmentPaste.test.ts
[warn] packages/editor/src/attachmentPaste.ts
[warn] packages/editor/src/blockHitTest.test.ts
[warn] packages/editor/src/blockHitTest.ts
[warn] packages/editor/src/blockSelectDecoration.ts
[warn] packages/editor/src/blockSelection.ts
[warn] packages/editor/src/callout.ts
[warn] packages/editor/src/chromeInteraction.svelte.ts
[warn] packages/editor/src/collaborationHistoryKeys.ts
[warn] packages/editor/src/collaborationUndo.test.ts
[warn] packages/editor/src/components/CalloutView.svelte
[warn] packages/editor/src/components/ImageView.svelte
[warn] packages/editor/src/components/TaskItemView.svelte
[warn] packages/editor/src/composerNoteSession.test.ts
[warn] packages/editor/src/composerNoteSession.ts
[warn] packages/editor/src/extensions.dragHandle.test.ts
[warn] packages/editor/src/extensions.ts
[warn] packages/editor/src/formatCommands.svelte.test.ts
[warn] packages/editor/src/formatCommands.ts
[warn] packages/editor/src/image.ts
[warn] packages/editor/src/imagePipe.ts
[warn] packages/editor/src/index.ts
[warn] packages/editor/src/linkCommand.ts
[warn] packages/editor/src/listIndent.test.ts
[warn] packages/editor/src/listIndent.ts
[warn] packages/editor/src/markdown.roundtrip.svelte.test.ts
[warn] packages/editor/src/markdown.test.ts
[warn] packages/editor/src/markdown.ts
[warn] packages/editor/src/markdown.vectors.test.ts
[warn] packages/editor/src/moveBlock.ts
[warn] packages/editor/src/noteCards.test.ts
[warn] packages/editor/src/noteCards.ts
[warn] packages/editor/src/noteCardsDecoration.ts
[warn] packages/editor/src/slash.test.ts
[warn] packages/editor/src/slash.touch.svelte.test.ts
[warn] packages/editor/src/slash.ts
[warn] packages/editor/src/source.ts
[warn] packages/editor/src/syntaxHighlight.test.ts
[warn] packages/editor/src/syntaxHighlight.ts
[warn] packages/editor/src/syntaxLanguages.ts
[warn] packages/editor/src/wikilinkSyntax.ts
[warn] Code style issues found in 45 files. Run Prettier with --write to fix.

Code-format differences will not be changed in this comment-only job. Final checks follow after the required origin/dev update. No tests or builds run.

Committed `537cdebe95681c90fb7252e2d123b87216083d85` for #902. Added all 16 audit-listed module headers, documented the display splitter, parsed anchor counts and trailing range coordinates, replaced product comparisons with grammar and behavior descriptions, and replaced the untracked slash research path with the caller-owned command-list invariant. Comment-only source comparison preserves runtime tokens and test directives. No expectations changed. Prettier check output (exit 1): ```text Checking formatting... [warn] packages/editor/src/Editor.svelte [warn] packages/editor/src/Editor.svelte.test.ts [warn] packages/editor/src/anchor.test.ts [warn] packages/editor/src/anchor.ts [warn] packages/editor/src/attachmentPaste.test.ts [warn] packages/editor/src/attachmentPaste.ts [warn] packages/editor/src/blockHitTest.test.ts [warn] packages/editor/src/blockHitTest.ts [warn] packages/editor/src/blockSelectDecoration.ts [warn] packages/editor/src/blockSelection.ts [warn] packages/editor/src/callout.ts [warn] packages/editor/src/chromeInteraction.svelte.ts [warn] packages/editor/src/collaborationHistoryKeys.ts [warn] packages/editor/src/collaborationUndo.test.ts [warn] packages/editor/src/components/CalloutView.svelte [warn] packages/editor/src/components/ImageView.svelte [warn] packages/editor/src/components/TaskItemView.svelte [warn] packages/editor/src/composerNoteSession.test.ts [warn] packages/editor/src/composerNoteSession.ts [warn] packages/editor/src/extensions.dragHandle.test.ts [warn] packages/editor/src/extensions.ts [warn] packages/editor/src/formatCommands.svelte.test.ts [warn] packages/editor/src/formatCommands.ts [warn] packages/editor/src/image.ts [warn] packages/editor/src/imagePipe.ts [warn] packages/editor/src/index.ts [warn] packages/editor/src/linkCommand.ts [warn] packages/editor/src/listIndent.test.ts [warn] packages/editor/src/listIndent.ts [warn] packages/editor/src/markdown.roundtrip.svelte.test.ts [warn] packages/editor/src/markdown.test.ts [warn] packages/editor/src/markdown.ts [warn] packages/editor/src/markdown.vectors.test.ts [warn] packages/editor/src/moveBlock.ts [warn] packages/editor/src/noteCards.test.ts [warn] packages/editor/src/noteCards.ts [warn] packages/editor/src/noteCardsDecoration.ts [warn] packages/editor/src/slash.test.ts [warn] packages/editor/src/slash.touch.svelte.test.ts [warn] packages/editor/src/slash.ts [warn] packages/editor/src/source.ts [warn] packages/editor/src/syntaxHighlight.test.ts [warn] packages/editor/src/syntaxHighlight.ts [warn] packages/editor/src/syntaxLanguages.ts [warn] packages/editor/src/wikilinkSyntax.ts [warn] Code style issues found in 45 files. Run Prettier with --write to fix. ``` Code-format differences will not be changed in this comment-only job. Final checks follow after the required origin/dev update. No tests or builds run.

kayg commented

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

Author

Owner

Final comment-only commit for #902: 0bb14c0a05014baea59f1237955a26799ca5b131 (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 #902: `0bb14c0a05014baea59f1237955a26799ca5b131` (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(editor): explain anchor ownership and module roles (#902)

kayg commented

2026-10-03 00:35:38 +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#902

No description provided.

Rows
Columns