| name | mapping-audit |
| description | Use when checking kasane's catalog for bad arc mappings — after inserting or editing a series in Supabase, before cutting a release, when a user reports an episode pointing at the wrong chapter, or when asked to "audit the catalog", "check the mappings", or "find bad data". |
Mapping Audit
Arc mappings are hand-researched and written straight into Supabase. They pass through no code review, no CI, and no migration. A mistyped boundary ships to every client on next launch. This audit is the only gate between a typo and production.
Run it
bun run scripts/audit-mappings.ts
bun run scripts/audit-mappings.ts --errors-only
bun run scripts/audit-mappings.ts --series "One Piece"
bun run scripts/audit-mappings.ts --anilist
bun run scripts/audit-mappings.ts --json
bun run scripts/audit-mappings.ts --no-ignore
Exit code is 1 when any error survives, so it composes into a release gate.
What each code means
| Code | Severity | Meaning |
|---|
chapter-overlap / episode-overlap | error if 2+ shared units, warn if exactly 1 | Consecutive arcs claim the same unit. Two arcs answer one lookup and find returns the earlier one. One shared unit is ambiguous: adaptations routinely split a chapter or episode across an arc boundary. |
position-sequence | error | Positions are not a dense 0-based run, so display order is undefined. |
chapter-range-inverted, episode-range-inverted, non-positive-episode | error | Impossible range. Always a typo. |
negative-chapter | error | Chapter below 0. Chapter 0 is legal: publishers number prologue chapters 00. |
catalog-behind-anime | info | Arcs stop short of the anime's episode count while manga chapters are still unmapped. Expected whenever the anime outruns its source; confirm the stop was deliberate rather than an unfinished mapping. |
episode-null-sandwich | warn | An unadapted arc sits between two adapted ones. Real when the anime skipped that source and resumed after it; also what a misordered row looks like. |
chapter-gap / episode-gap | warn if the hole is 1-3 units, else info | Small holes are off-by-one typos; long runs are anime filler or deliberately skipped stretches. |
season-partial | warn | Some adapted arcs carry season, some do not. Per-season coverage UI needs all or none. |
movie-* | warn | A film's chapter range or after_episode falls outside the mapped arcs. |
catalog-behind-manga | warn | The manga has published past the last mapped arc. Feed this to mapping-correction. |
anime-original-pinned | info | A zero-width arc pinned at the previous arc's last chapter. chapter_start/chapter_end are NOT NULL, so this is the schema's only way to say "adapts no further manga". Normal, not a defect. |
shared-manga-id | info | Two series share a manga id. The lowest series id wins the lookup. Confirm the winner is the one users expect. |
Triage before fixing
Not every finding is a bug. These modelling choices produce findings legitimately:
- Light-novel adaptations store LN volume numbers in the chapter columns, so ranges overlap and skip freely. Tell: arc names containing "Vol", "LN", or "Novel".
- Anime-original arcs woven mid-stream share a boundary chapter with the arc around them.
- Non-linear adaptations (a season that backfills chapters an earlier season skipped) genuinely overlap.
- Episodic anthologies reorder chapters freely. Tell: episode titles that concatenate the chapter titles they adapt.
- Straddling boundaries where one chapter or episode is split across two arcs. Tell: the show's wiki lists that unit under both arcs, often marked "(Partially)".
- Mid-run skipped source where the anime jumps a volume or arc and resumes after it, leaving an unadapted arc between two adapted ones.
- Deliberately partial mappings of very long shows leave large gaps on purpose.
The first full triage pass found that only 2 of 16 reported errors were real data bugs. Assume a finding is a modelling choice until a primary source says otherwise, and when a whole class of finding turns out legitimate, fix the check rather than filing another ignore entry.
Confirm the intent from the arc name, the note, or source_notes before touching data. When a finding is intentional, record it in scripts/audit-ignore.json with a reason:
"Toilet-bound Hanako-kun": {
"chapter-overlap": "S1 skipped chapters 23-29 and S2 backfilled them, so the season ranges genuinely overlap"
}
Suppression is per series + code, so a new bug of an already-triaged code in an already-triaged series stays hidden. Re-run with --no-ignore whenever you edit a series that has an entry there.
Fixing what is real
Corrections are Supabase writes, not code changes. Use the mapping-correction skill. Never edit rows to silence the audit without confirming the underlying fact against the fandom wiki or Wikipedia first.
Common mistakes
| Mistake | Why it hurts |
|---|
| Adding an ignore entry to make the output green | The audit exists to be believed. An unjustified entry makes every future run less trustworthy. |
Treating every chapter-gap as a bug | Most long gaps are anime filler. Fix the 1-3 unit ones first. |
Treating catalog-behind-anime as a defect | It compares two different quantities: episodes that adapt manga vs every episode aired. An anime outrunning its source is the common case, so this is info. |
| Editing rows with the app's publishable key | Catalog tables are read-only under RLS. Write via Supabase MCP, the dashboard, or a service-role script. |
