[nightshift] tech-debt-classify: Technical Debt Classification

[nightshift-micr]

Technical Debt Classification Report — micr-dev/blog

Summary

Severity	Count
P0 (blocks future work)	2
P1 (should fix soon)	7
P2 (plan to address)	10
P3 (nice to have)	7

---

P0 — Blocks Future Work

TD-01: Duplicated SVG Processing Logic (tintSvg, cropScytheSvg, svgToDataUri)

• Type: Architecture Debt
• Files: src/app/(enhanced)/blog/[slug]/opengraph-image.tsx (lines 24–39), src/lib/og-assets.ts (lines 18–33)
• Detail: Three identical utility functions are copy-pasted between the OG image route and the og-assets module. If one set is updated, the other will silently diverge.
• Impact: Any change to SVG processing must be applied in two places. Divergence will cause OG previews and production OG images to render differently.
• Effort: Low (< 1 hour) — consolidate into src/lib/og-assets.ts and import from the route.

TD-02: Hardcoded Domain in Blog Post Page Metadata

• Type: Code Debt
• File: src/app/(enhanced)/blog/[slug]/page.tsx (lines 38, 43)
• Detail: Two places use the string literal https://blog.micr.dev instead of siteConfig.domain:

  canonical: `https://blog.micr.dev/blog/${post.slug}`,  // line 38
  url: `https://blog.micr.dev/blog/${post.slug}`,         // line 43

  Every other page correctly uses https://${siteConfig.domain}.
• Impact: Domain migration or staging deployment will produce incorrect canonical URLs and OpenGraph URLs on blog post pages. Also affects SEO.
• Effort: Low (< 1 hour)

---

P1 — Should Fix Soon

TD-03: Unsafe CSS Custom Property Type Casting

• Type: Code Debt
• File: src/lib/mdx.tsx (lines 79–89)
• Detail: 11 occurrences of ["--post-background" as string] bypass TypeScript's type checking for CSS custom properties. Renaming/removing a CSS variable won't produce compile-time errors.
• Effort: Medium (1–4 hours)

TD-04: dangerouslySetInnerHTML Without Sanitization

• Type: Code Debt
• Files: src/components/mdx/mermaid-fence.tsx (line 89), src/components/mdx/code-fence.tsx (line 62)
• Detail: Both inject raw HTML. Mermaid's render() output is dynamically generated from user-authored MDX content — potential XSS vector if untrusted content is processed.
• Effort: Low (< 1 hour) — add DOMPurify for Mermaid output.

TD-05: Font Loading Path Guessing in Signature Component

• Type: Code Debt
• File: src/components/spell-ui/signature.tsx (lines 40–56)
• Detail: Tries three different paths to load the font file in a try/catch loop. Fragile, error is swallowed.
• Effort: Medium (1–4 hours)

TD-06: Brand SVG File Reads Not DRY

• Type: Architecture Debt
• File: src/app/(enhanced)/blog/[slug]/opengraph-image.tsx (lines 73–76)
• Detail: Reads brand SVGs directly via fs.readFile instead of using the cached readBrandSvg helper. Duplicate I/O during static generation for every post.
• Effort: Low (< 1 hour)

TD-07: Hardcoded Color Values in CSS and JS

• Type: Code Debt
• Files: src/app/globals.css (lines 519, 525), src/components/mdx/mermaid-fence.tsx (lines 12–13), src/components/footer.tsx (line 27)
• Detail: Colors hardcoded in multiple locations. Footer copyright year is a literal string that will become outdated.
• Effort: Medium (1–4 hours)

TD-08: Outdated agentation Dependency

• Type: Dependency Debt
• File: package.json
• Detail: agentation pinned at ^2.3.3 but latest is 3.0.2. Major version bump may contain breaking changes.
• Effort: Low (< 1 hour)

TD-09: Test Coverage Gaps

• Type: Test Debt
• Detail: Only 3 test files exist. Missing tests for: mermaid-ascii.ts, post-parser.ts, code-fence.tsx (color math), page-level components, signature component.
• Effort: High (> 4 hours)

---

P2 — Plan to Address

ID	Finding	Type	Effort
TD-10	Large page components not extracted (191-line blog post page)	Architecture	Medium
TD-11	Duplicated adjacent posts/footer pattern between enhanced and plain pages	Code	Medium
TD-12	Duplicated tag page structure (4 near-identical tag pages)	Code	Medium
TD-13	remarkUnwrapStandaloneMedia uses unsafe type assertions	Code	Medium
TD-14	package.json name is "blog2"	Code	Low
TD-15	No error boundary for client-side Mermaid rendering	Code	Low
TD-16	Global error boundary uses CSS variables without explicit CSS import	Architecture	Low
TD-17	Local editor stores theme defaults in template string (will drift from defaultPostTheme)	Code	Low
TD-18	OG preview route has no production guard (publicly accessible internal tool)	Code	Low
TD-19	CSS file is 526 lines without organization	Code	Medium

---

P3 — Nice to Have

ID	Finding	Type	Effort
TD-20	LinkedIn icon uses external PNG mask instead of SVG path	Code	Low
TD-21	No loading/error state for PostList component	Architecture	Low
TD-22	cn() utility doesn't handle Tailwind class conflicts	Code	Low
TD-23	prism-react-renderer listed as dependency but unused (codebase uses shiki)	Dependency	Low
TD-24	No @types/mdast or unified type imports	Code	Low
TD-25	vitest.config.ts aliases next/link (fragile on upgrades)	Test	Low
TD-26	No documentation for content authoring (MDX components, theme system)	Documentation	Medium

---

Priority Action Plan

Priority	Item	Effort	Action
P0	TD-01	Low	Consolidate SVG utils into og-assets.ts
P0	TD-02	Low	Replace hardcoded domain with siteConfig
P1	TD-06	Low	Use readBrandSvg in opengraph-image route
P1	TD-08	Low	Update agentation to v3
P1	TD-18	Low	Add dev guard to OG preview route
P1	TD-04	Low	Add sanitization for Mermaid output
P1	TD-07	Medium	Extract hardcoded colors to theme/config
P1	TD-03	Medium	Type CSS custom properties properly
P1	TD-05	Medium	Fix font loading in Signature component

Total estimated effort to resolve P0 + P1 items: ~8–12 hours

---

Automated by Nightshift v3 (GLM 5.1) • Task: tech-debt-classify • Category: options