Add repository technical audit and improvement plan

[alexander-yevsyukov]

Summary

Adds a full technical audit of embed-code-go in two shareable formats:

• embed-code-go-audit.md — diff-friendly Markdown source.
• embed-code-go-audit.html — self-contained rendering (embedded CSS, light/dark, works offline; Print → Save as PDF to export).

This is documentation only — no source code is changed.

What the report covers

Severity-rated findings (each citing file:line) across architecture, code quality, security, testing, performance, dependencies, DevEx, and documentation — plus a strengths section, an improvement strategy, and a milestone-based task plan with quick wins.

Overall grade: B+ (Good) — strong engineering discipline (40-linter CI, multi-OS testing, 75.9% integrated coverage, clean layered design), held back by a few concrete issues.

Headline findings

• High — confirmed runtime panic in indent.CutIndent (indent/indent.go:65), reproduced from realistic input (a whitespace-only line shorter than the block indentation → slice bounds out of range [8:2]).
• High — 206 MB .git from auto-committing the bin/ binaries on every master push.
• High — Kotlin nested block comments mishandled by the heuristic comment filter (marker_comment_filter.go:123-137).
• Medium — tests require -p 1 (shared ../test/docs + global resolver cache); orchestration in main.go and cache LRU eviction are 0% covered.

Decisions already baked into the plan

GitHub Releases for binaries; purge bin/ history (gated maintenance op); external consumption; Apache-2.0 license; comment-filter reliability prioritized Kotlin → Java → TS → JS → C# → C++ → Python → Go → VB.

Next step

The report proposes Milestone 0 (test safety net) + the panic fix as a low-risk first implementation PR.

🤖 Generated with Claude Code

https://claude.ai/code/session_01HjNupDuDDodqQ4xTncNXqL

---

Generated by Claude Code

[alexander-yevsyukov]

@codex review.

[alexander-yevsyukov]

@Oleg-Melnik, presumably, these documents should go under .agents/tasks. This is how we do in the rest of the Spine projects. This is a preferred location, but you may want to override it, if you have very good reasons for this.

[Copilot]

Pull request overview

Adds a shareable technical audit + improvement plan for the embed-code-go repository in both a diff-friendly source format (Markdown) and a self-contained offline-readable format (HTML). This fits the codebase as a planning/roadmap artifact to guide follow-up implementation PRs without changing production code.

Changes:

• Added embed-code-go-audit.md containing the full audit report with severity-rated findings, citations, and a milestone-based task plan.
• Added embed-code-go-audit.html as a standalone rendered version (embedded CSS, light/dark, printable to PDF).
• Documented owner decisions/constraints (license choice, binary distribution strategy, comment-filter language priorities).

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File	Description
embed-code-go-audit.md	New Markdown audit report and improvement plan (source-of-truth, diff-friendly).
embed-code-go-audit.html	New standalone HTML rendering of the same audit content for offline viewing/printing.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c658029240

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[alexander-yevsyukov]

Thanks for the reviews — addressed the feedback in 8823296 (HTML regenerated from the corrected Markdown).

Codex (accuracy — both valid):

• License: corrected. The per-file headers are already a BSD-style permissive grant, so the document now frames the gap as the absence of a standard root license (hence standardizing on Apache-2.0) rather than "no grant for external use."
• -p 1: agreed. go test -p governs cross-package parallelism, and the cited state (../test/docs, the resolver cache) is package-local with no shared writable path crossing packages — so it doesn't by itself force -p 1. Reworded and demoted from the top-three risks, retained as a Medium test-isolation smell; the confirmed Kotlin comment-filter defect takes the third risk slot.

Copilot:

• Fixed the #e4e8 ; CSS hex typo in the generated HTML.
• Table accessibility: key/value tables now have real headers and every <th> carries scope="col" (no empty header cells).
• Reworded the closing note ("in its production" → "in its preparation"), in both formats.

---

Generated by Claude Code

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.