From 20a824118c09af15d6c338db4c9480ffe5cbcdb6 Mon Sep 17 00:00:00 2001 From: Christophe Besson Date: Sat, 19 Sep 2026 02:12:47 +0200 Subject: docs: cite MESHBAY_DESIGN.md and a section instead of the merged notes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The per-feature design notes were merged into docs/MESHBAY_DESIGN.md and deleted from the tree on 2026-09-11, but ~230 comments across the three packages still named them — usually written `docs/musicbay.md §3.2`, as though the file were still in docs/. A reader had to know §16 existed to resolve any of them. They now name the section directly. Every mapping comes from §16, the concordance, which already records where each old section landed: musicbay -> §9.8, mediacenter -> §9.7 for the Videos app and §6.5 where the subject is derived data, photos -> §9.9, auth-confirm -> §3.6, refactoring-search -> §9.11, invite-pairing-v1 -> §3.4, per-node-identity-v1 -> §3.2, captcha -> §7.7, chat-sender-keys -> §4.5, apps/refactor-groups -> §9.1–§9.4, desktop-client-v1 per section. Bare citations of the same documents (`draft-v6 §2.11`, `§4.8`, `§3.4`) are retargeted too: those collide with real section numbers in the design document, so leaving them would have been worse than the named form. Four cases the concordance does not cover, each decided rather than guessed: Sub-item references into documents that no longer exist — mediacenter's `§3.3 row 4`, `§3.4b/c`, `apps.md §3b` — name rows and sub-items §9.7 and §9.2 do not reproduce. The module-level citation stays; the sub-item pointer is dropped. The V-findings keep their labels but lose the dead `§10.1/` prefix. §13.8 lists V1–V13 as per-application open items, which is not what the labels mean in these comments, so pointing them at §13.8 would have been a false citation. `apps.md §5`'s virtualization requirement has no counterpart anywhere in the design document. The requirement is stated in the comment itself, so the citation is dropped rather than aimed at a section that does not say it. Comments that attributed a *sentence* to an old note — musicbay's "several thousand files" example, its "what got measured" note, its measured ~11%/~26% cover-art figures, the "original no root, whole shared tree" call — state the fact without attribution now. §9.8 does not contain those sentences and citing it for them would have been wrong. CLAUDE.md's "a reference to a document that no longer exists" row now says the concordance is for git history and out-of-tree material; the code cites sections directly. Verified: 2851 passed, 4 skipped. The 12 errors in the run are the Firefox leg of test_sticky_header.py's browser harness, which is broken at the browser level on this machine — headless Firefox (snap) dies with `[GFX1-]: RenderCompositorSWGL failed mapping default framebuffer`, renders nothing, and the probe exits `{"error": "no measurement"}` after its full 90s wait. Chrome runs the same 12 assertions in 3.2s and passes. Nothing here can affect it: every changed line in style.css is inside a comment. Also checked: ast.parse on every changed .py, `node --check` on every changed .js, the /* */ balance in style.css, and that no changed line exceeds the width its file already used. Co-Authored-By: Claude Opus 5 --- .../src/meshbay_node/indexer/enrich.py | 64 ++++++++++++---------- 1 file changed, 34 insertions(+), 30 deletions(-) (limited to 'packages/meshbay-node/src/meshbay_node/indexer/enrich.py') diff --git a/packages/meshbay-node/src/meshbay_node/indexer/enrich.py b/packages/meshbay-node/src/meshbay_node/indexer/enrich.py index 6eeb1ef..b44a246 100644 --- a/packages/meshbay-node/src/meshbay_node/indexer/enrich.py +++ b/packages/meshbay-node/src/meshbay_node/indexer/enrich.py @@ -4,7 +4,7 @@ filename parsing (title_parse), and thumbnail generation (ffmpeg) for a newly-added video IndexEntry. Runs through its own small bounded worker pool — separate from the streaming -transcode pool (docs/mediacenter.md §5.2, mirroring webrtc_server.py's +transcode pool (docs/MESHBAY_DESIGN.md §6.5, mirroring webrtc_server.py's `_transcode_semaphore`) — so indexing a large library never blocks on this, and enrichment never competes with an active viewer for CPU. The scan itself already put the entry in the index with hash/size/type only; this fills in @@ -33,26 +33,27 @@ THUMB_WIDTH = 320 # "Show/SeasonFolder/episode.mkv" is the expected shape, with a little slack # for an extra wrapper folder — not an attempt to find the exact group root. MAX_ANCESTOR_DEPTH = 4 -# Bounds the "borrow a title from a sibling episode filename" scan (§3.4) so -# a folder with thousands of files costs a fixed, small amount of work. +# Bounds the "borrow a title from a sibling episode filename" scan +# (docs/MESHBAY_DESIGN.md §9.7) so a folder with thousands of files costs a +# fixed, small amount of work. MAX_SIBLINGS_CHECKED = 20 # Bounds the whole-show scan _synthetic_episode_number uses to rank a -# season's files across more than one folder (§3.4c) — a show's total file -# count, not just one folder's, so this needs more headroom than -# MAX_SIBLINGS_CHECKED. +# season's files across more than one folder (docs/MESHBAY_DESIGN.md §9.7) — +# a show's total file count, not just one folder's, so this needs more +# headroom than MAX_SIBLINGS_CHECKED. MAX_SEASON_FILES_CHECKED = 500 def _season_and_show_from_ancestors(file_path: Path) -> tuple[int, Path] | None: """ - §3.4/§3.4c: walk up ancestor folders for a season-like one (a numbered - season, or Specials/Bonus/Extras -> season 0) — season from the first - (innermost) match, but the show's own name from *above every - consecutive season-like ancestor*, not just the first one. A - per-season Bonus folder (`Show/Season N/Bonus/file.ext`) is nested two - levels inside the show, both of them season-like on their own - ("Bonus" and "Season N") — stopping at the first would hand back - "Season N" as the show's name instead of "Show". + docs/MESHBAY_DESIGN.md §9.7: walk up ancestor folders for a season-like one + (a numbered season, or Specials/Bonus/Extras -> season 0) — season from the + first (innermost) match, but the show's own name from *above every + consecutive season-like ancestor*, not just the first one. A per-season + Bonus folder (`Show/Season N/Bonus/file.ext`) is nested two levels inside + the show, both of them season-like on their own ("Bonus" and "Season N") — + stopping at the first would hand back "Season N" as the show's name instead + of "Show". Trusted over any per-file guessit title once found: a bare episode numbering convention with no show name embedded at all @@ -87,15 +88,17 @@ def _season_and_show_from_ancestors(file_path: Path) -> tuple[int, Path] | None: def _title_from_siblings(file_path: Path) -> str | None: """ - §3.4: an episode filename with no show name in it borrows the title from - a representative sibling in the same folder, never from the folder name - alone (an acronym-named show folder is a real, observed case). + docs/MESHBAY_DESIGN.md §9.7: an episode filename with no show name in it + borrows the title from a representative sibling in the same folder, never + from the folder name alone (an acronym-named show folder is a real, + observed case). Requires the sibling to carry its own episode number too, not just a - title — a folder where every file is a one-off-named Special (§3.4b) - has plenty of `display_title`s (guessit reads *a* title off nearly - anything) but none of them name the show; requiring a real episode - number alongside is what tells apart a genuinely representative sibling + title — a folder where every file is a one-off-named Special + (docs/MESHBAY_DESIGN.md §9.7) has plenty of `display_title`s (guessit + reads *a* title off nearly anything) but none of them name the show; + requiring a real episode number alongside is what tells apart a + genuinely representative sibling from another Special just like this one. """ try: @@ -119,11 +122,11 @@ def _title_from_siblings(file_path: Path) -> str | None: def _synthetic_episode_number(file_path: Path, show_root: Path, season: int) -> int: """ - §3.4b/§3.4c: a Specials/Bonus folder's files often carry no episode - number at all — each is just named after its own one-off title. The - frontend (video-app.js's buildSeasons) sorts within a season by this - number but only needs it to provide a stable order, not to mean - anything beyond that. + docs/MESHBAY_DESIGN.md §9.7: a Specials/Bonus folder's files often carry no + episode number at all — each is just named after its own one-off title. The + frontend (video-app.js's buildSeasons) sorts within a season by this number + but only needs it to provide a stable order, not to mean anything beyond + that. Ranked across the *whole show*, not just this file's own folder: season 0 routinely spans more than one folder under the show's root — a @@ -289,10 +292,11 @@ class Enricher: and (title_parse.has_episode_marker(entry.name) or title_parse.year_in(entry.name) is None)): # No season-like ancestor at all (a flat library) but the - # filename itself carries season+episode (§3.4) — *and* it - # is a real marker, not guessit reading a bare number as - # SxxExx. A movie whose "1080p" tag was truncated to "108", - # or "1280" left in the name, otherwise parses to S01E08 / + # filename itself carries season+episode + # (docs/MESHBAY_DESIGN.md §9.7) — *and* it is a real marker, + # not guessit reading a bare number as SxxExx. A movie whose + # "1080p" tag was truncated to "108", or "1280" left in the + # name, otherwise parses to S01E08 / # S12E80 and gets shelved as a nonexistent series # (found live 2026-08-29). A genuine flat-dumped episode # has an explicit SxxExx/1x08/"Episode N" marker; a movie -- cgit v1.2.3