Gitlab Docs Publishing

/* Game AI QA — Doc comments widget styles
 *
 * Minimal: just the floating "💬 添加评论" bubble that appears above a text
 * selection. Click → opens GitLab Issue creation in a new tab.
 */

/* ── Bubble (selection floater) ────────────────────────────────────────── */
#dc-bubble {
  position: absolute;
  z-index: 9999;
  display: inline-block;
  background: #ff9900;
  color: #fff;
  font: 600 12px/1.2 -apple-system, system-ui, "Segoe UI", "PingFang SC", sans-serif;
  border-radius: 16px;
  padding: 6px 12px;
  cursor: pointer;
  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.18);
  user-select: none;
  white-space: nowrap;
  text-decoration: none;
  transition: background 0.12s, transform 0.08s;
}
#dc-bubble:hover { background: #e88b00; }
#dc-bubble:active { transform: scale(0.96); }
#dc-bubble[hidden] { display: none; }

/* Game AI QA — In-page Doc Comments (selection → new GitLab Issue)
 *
 * Reviewer selects any text or block element. A floating "💬 添加评论" bubble
 * appears above the selection. Clicking opens a new tab on GitLab's Issue
 * creation page with title + description prefilled — reviewer's Midway/SSO
 * session authenticates them automatically. No CORS/OAuth/PAT involved.
 *
 * Why this shape: AEA + GitLab CORS make any in-browser API call impossible
 * from the Pages origin. Plain navigation works because the browser handles
 * the auth handshake itself.
 *
 * Config injected as window.__DOC_COMMENTS_CONFIG__ before this script.
 */
(function () {
  'use strict';

  // ─── Config ──────────────────────────────────────────────────────────────
  var cfg = window.__DOC_COMMENTS_CONFIG__ || {};
  var required = ['gitlabHost', 'projectPath', 'pageKey', 'pageUrl'];
  var missing = required.filter(function (k) { return !cfg[k]; });
  if (missing.length) {
    showSetupBanner('Doc comments not yet enabled — missing config: ' + missing.join(', '));
    return;
  }
  var TITLE_PREFIX = cfg.titlePrefix || '[doc-comment]';
  var ISSUE_LABELS = cfg.issueLabels || 'doc-comments';

  // ─── Anchor model ────────────────────────────────────────────────────────
  // Same shape as before so the JSON in the issue body is forward-compatible
  // if we ever add an in-page reader that fetches & re-locates anchors.
  function anchorFromRange(range) {
    if (range.collapsed) return null;
    var exact = range.toString().slice(0, 280);
    if (!exact.trim()) return null;
    var prefix = textBefore(range, 32);
    var suffix = textAfter(range, 32);
    var startEl = range.startContainer.nodeType === 1
      ? range.startContainer
      : range.startContainer.parentElement;
    var heading = findOwningHeading(startEl);
    return {
      type: 'text',
      id: heading && heading.id ? heading.id : null,
      sectionTitle: heading ? cleanHeadingText(heading) : null,
      exact: exact,
      prefix: prefix,
      suffix: suffix,
    };
  }
  // Walk back through previous siblings + their descendants, then up the tree,
  // collecting the deepest (highest-level h-tag number) heading seen so far.
  // Stops as soon as we find a heading that owns the current node.
  function findOwningHeading(el) {
    var node = el;
    while (node && node !== document.body) {
      // 1. Check this node itself if it's a heading
      if (/^H[1-6]$/.test(node.tagName)) return node;
      // 2. Walk back through preceding siblings looking for a heading
      var sib = node.previousElementSibling;
      while (sib) {
        var h = lastHeadingIn(sib);
        if (h) return h;
        sib = sib.previousElementSibling;
      }
      node = node.parentElement;
    }
    return null;
  }
  // Return the LAST heading inside `el` (so a section's last subsection wins
  // over its parent title when selecting text under that subsection).
  function lastHeadingIn(el) {
    if (!el || el.nodeType !== 1) return null;
    if (/^H[1-6]$/.test(el.tagName)) return el;
    var hs = el.querySelectorAll && el.querySelectorAll('h1, h2, h3, h4, h5, h6');
    if (hs && hs.length) return hs[hs.length - 1];
    return null;
  }
  function cleanHeadingText(h) {
    return (h.textContent || '').trim().replace(/\s+/g, ' ').slice(0, 80);
  }
  function textBefore(range, n) {
    var s = range.startContainer.textContent || '';
    return s.slice(Math.max(0, range.startOffset - n), range.startOffset);
  }
  function textAfter(range, n) {
    var s = range.endContainer.textContent || '';
    return s.slice(range.endOffset, range.endOffset + n);
  }

  // ─── Title + description for the GitLab Issue ───────────────────────────
  // Format: "[doc-comment] §<section-title> · <selection-quote>"
  // Section title comes from the heading the selection sits under (when available).
  // Falls back to the anchor id, then to the page key. Selection quote is short
  // (first ~30 chars, ellipsised) so the title stays scannable.
  function buildTitle(anchor) {
    var section = anchor.sectionTitle || anchor.id || cfg.pageKey;
    var quote = (anchor.exact || '').replace(/\s+/g, ' ').trim();
    if (quote.length > 30) quote = quote.slice(0, 30) + '…';
    var parts = [TITLE_PREFIX, '§' + section];
    if (quote) parts.push('· "' + quote + '"');
    return parts.join(' ').slice(0, 240);
  }

  function buildDescription(anchor) {
    var anchorUrl = cfg.pageUrl + (anchor.id ? '#' + anchor.id : '');
    var anchorLabel = anchor.sectionTitle || anchor.id || cfg.pageKey;
    var lines = [];
    lines.push('**Anchor**: [§' + anchorLabel + '](' + anchorUrl + ')');
    lines.push('');
    lines.push('**Selection**:');
    lines.push('> ' + (anchor.exact || '').replace(/\n/g, '\n> '));
    lines.push('');
    lines.push('---');
    lines.push('');
    lines.push('<!-- doc-comment-anchor-v1');
    lines.push(JSON.stringify({ anchor: anchor, page: cfg.pageKey }));
    lines.push('-->');
    lines.push('');
    lines.push('Your comment:');
    lines.push('');
    return lines.join('\n');
  }

  function buildIssueUrl(anchor) {
    var base = cfg.gitlabHost + '/' + cfg.projectPath + '/-/issues/new';
    var p = new URLSearchParams();
    p.set('issue[title]', buildTitle(anchor));
    p.set('issue[description]', buildDescription(anchor));
    if (ISSUE_LABELS) p.set('issue[label_names][]', ISSUE_LABELS);
    return base + '?' + p.toString();
  }

  // ─── Bubble UI ───────────────────────────────────────────────────────────
  var bubble;
  function build() {
    bubble = document.createElement('a');
    bubble.id = 'dc-bubble';
    bubble.target = '_blank';
    bubble.rel = 'noopener noreferrer';
    bubble.hidden = true;
    bubble.textContent = '💬 添加评论';
    document.body.appendChild(bubble);

    // Keep selection while clicking the bubble.
    bubble.addEventListener('mousedown', function (e) { e.preventDefault(); });

    document.addEventListener('mouseup', maybeShowBubble);
    document.addEventListener('selectionchange', maybeShowBubble);
    document.addEventListener('scroll', repositionBubble, { passive: true });
    window.addEventListener('resize', repositionBubble);
  }

  var lastRect = null;
  function maybeShowBubble() {
    var sel = window.getSelection();
    if (!sel || sel.isCollapsed || sel.rangeCount === 0) {
      bubble.hidden = true;
      lastRect = null;
      return;
    }
    var range = sel.getRangeAt(0);
    var text = range.toString();
    if (!text || !text.trim()) {
      bubble.hidden = true;
      lastRect = null;
      return;
    }
    if (bubble.contains(range.startContainer)) return;
    var anchor = anchorFromRange(range);
    if (!anchor) {
      bubble.hidden = true;
      return;
    }
    bubble.href = buildIssueUrl(anchor);
    lastRect = range.getBoundingClientRect();
    repositionBubble();
    bubble.hidden = false;
  }

  function repositionBubble() {
    if (!lastRect || bubble.hidden) return;
    var r = lastRect;
    bubble.style.top = (window.scrollY + r.top - 40) + 'px';
    bubble.style.left = (window.scrollX + r.left + r.width / 2 - 64) + 'px';
  }

  // ─── Setup-banner (only when config missing) ────────────────────────────
  function showSetupBanner(msg) {
    var b = document.createElement('div');
    b.id = 'dc-setup-banner';
    b.textContent = msg;
    b.style.cssText = 'position:fixed;top:0;left:0;right:0;background:#ffe9b2;' +
                      'color:#7a4a00;padding:10px 16px;font:13px system-ui;' +
                      'z-index:99999;border-bottom:1px solid #d8a520;';
    if (document.body) document.body.appendChild(b);
    else document.addEventListener('DOMContentLoaded', function () { document.body.appendChild(b); });
  }

  // ─── Public API for testing ─────────────────────────────────────────────
  window.docComments = {
    buildIssueUrl: buildIssueUrl,
    anchorFromRange: anchorFromRange,
  };

  // ─── Boot ───────────────────────────────────────────────────────────────
  if (document.readyState === 'loading') {
    document.addEventListener('DOMContentLoaded', build);
  } else {
    build();
  }
})();

#!/usr/bin/env python3
"""Inject the doc-comments widget into a published HTML file.

Idempotent: running twice does not duplicate <link>/<script> tags.
Zero deps (stdlib only).

Usage (typical CI):
  python3 scripts/inject-comments.py \
      --html docs/v1.0.0/tech-design.html \
      --out  public/v1.0.0/index.html \
      --assets-dir public/v1.0.0/_assets \
      --assets-url _assets \
      --config-json docs/v1.0.0/comments-issue.json \
      --page-key v1.0.0/tech-design.html
"""
from __future__ import annotations

import argparse
import json
import re
import shutil
import sys
from pathlib import Path

INJECTED_META = '<meta name="doc-comments-injected" content="v1">'
SCRIPT_NAME = 'comment-widget.js'
STYLE_NAME = 'comment-widget.css'

# ─── Heading id slugger ────────────────────────────────────────────────────

_slug_strip = re.compile(r'[^\w一-鿿\- ]+', re.UNICODE)
_ws = re.compile(r'\s+')


def slugify(text: str) -> str:
    text = (text or '').strip().lower()
    text = _slug_strip.sub('', text)
    text = _ws.sub('-', text).strip('-')
    return text or 'sec'


# ─── Heading id ensure ─────────────────────────────────────────────────────

HEADING_RE = re.compile(r'<(h[1-6])(\s[^>]*)?>(.*?)</\1>', re.DOTALL | re.IGNORECASE)
ID_ATTR_RE = re.compile(r'\bid\s*=\s*"([^"]*)"', re.IGNORECASE)
TAG_TEXT_RE = re.compile(r'<[^>]+>')


def ensure_heading_ids(html: str) -> str:
    seen: set[str] = set()

    # First pass: collect existing ids so we don't collide.
    for m in re.finditer(r'\bid\s*=\s*"([^"]*)"', html, re.IGNORECASE):
        seen.add(m.group(1))

    def repl(m: re.Match) -> str:
        tag = m.group(1)
        attrs = m.group(2) or ''
        inner = m.group(3)
        if ID_ATTR_RE.search(attrs):
            return m.group(0)
        text = TAG_TEXT_RE.sub('', inner).strip()
        slug = slugify(text)
        cand = slug
        i = 2
        while cand in seen:
            cand = f'{slug}-{i}'
            i += 1
        seen.add(cand)
        new_attrs = (attrs or '') + f' id="{cand}"'
        return f'<{tag}{new_attrs}>{inner}</{tag}>'

    return HEADING_RE.sub(repl, html)


# ─── Figure / table id helpers (best effort, mirrors existing skill style) ─

DIAGRAM_FRAME_RE = re.compile(
    r'<div([^>]*\bclass="[^"]*diagram-frame[^"]*"[^>]*)>',
    re.IGNORECASE,
)
TABLE_WRAP_RE = re.compile(
    r'<div([^>]*\bclass="[^"]*aws-table-wrap[^"]*"[^>]*)>',
    re.IGNORECASE,
)


# ─── Strip stale `<a class="discuss-btn">` markup if present ────────────
# Source HTML produced by older versions of this skill (≤ v1.x) carried
# per-heading 💬 buttons. The v2 selection bubble covers that use case,
# so we strip those legacy anchors from the published artifact (the
# source HTML is left untouched). If your source HTML doesn't have them,
# this is a no-op and safe to keep.

LEGACY_BTN_RE = re.compile(
    r'<a\s+class="discuss-btn"[^>]*>.*?</a>',
    re.DOTALL | re.IGNORECASE,
)
LEGACY_CSS_RULE_RE = re.compile(
    r'\.discuss-btn[^{}]*\{[^{}]*\}',
    re.IGNORECASE,
)


def strip_legacy_discuss_buttons(html: str) -> tuple[str, int]:
    new_html, btn_count = LEGACY_BTN_RE.subn('', html)
    new_html = LEGACY_CSS_RULE_RE.sub('', new_html)
    return new_html, btn_count


def add_sequential_ids(html: str, regex: re.Pattern, prefix: str) -> str:
    counter = {'n': 0}

    def repl(m: re.Match) -> str:
        attrs = m.group(1)
        if ID_ATTR_RE.search(attrs):
            return m.group(0)
        counter['n'] += 1
        return f'<div{attrs} id="{prefix}-{counter["n"]}">'

    return regex.sub(repl, html)


# ─── Injection ─────────────────────────────────────────────────────────────

def already_injected(html: str) -> bool:
    return 'name="doc-comments-injected"' in html


def build_config_snippet(
    *, gitlab_host: str, project_path: str,
    page_key: str, page_url: str,
    title_prefix: str, issue_labels: str,
) -> str:
    payload = {
        'gitlabHost': gitlab_host,
        'projectPath': project_path,
        'pageKey': page_key,
        'pageUrl': page_url,
        'titlePrefix': title_prefix,
        'issueLabels': issue_labels,
    }
    js = json.dumps(payload, ensure_ascii=False)
    return f'<script>window.__DOC_COMMENTS_CONFIG__ = {js};</script>'


def inject_assets(html: str, assets_rel: str, config_snippet: str) -> str:
    if already_injected(html):
        return html

    head_inject = (
        f'  {INJECTED_META}\n'
        f'  <link rel="stylesheet" href="{assets_rel}/{STYLE_NAME}">\n'
    )
    body_inject = (
        f'  {config_snippet}\n'
        f'  <script src="{assets_rel}/{SCRIPT_NAME}" defer></script>\n'
    )

    if '</head>' in html:
        html = html.replace('</head>', head_inject + '</head>', 1)
    else:
        html = head_inject + html  # no <head>; degrade

    if '</body>' in html:
        html = html.replace('</body>', body_inject + '</body>', 1)
    else:
        html = html + body_inject

    return html


# ─── Driver ────────────────────────────────────────────────────────────────

def main() -> int:
    p = argparse.ArgumentParser()
    p.add_argument('--html', required=True, help='Input HTML file')
    p.add_argument('--out', required=True, help='Output HTML file (e.g. public/v1.0.0/index.html)')
    p.add_argument('--assets-dir', required=True, help='Where comment-widget.{js,css} get copied')
    p.add_argument('--assets-url', default='_assets',
                   help='URL path (relative to the HTML) where the browser fetches assets')
    p.add_argument('--config-json', required=True,
                   help='Path to comments-issue.json (gitlabHost + projectPath + pageUrl)')
    p.add_argument('--page-key', required=True, help='Logical key stored with each comment')
    args = p.parse_args()

    src_path = Path(args.html)
    out_path = Path(args.out)
    assets_dir = Path(args.assets_dir)
    cfg_path = Path(args.config_json)

    if not src_path.is_file():
        print(f'ERROR: html not found: {src_path}', file=sys.stderr)
        return 2
    if not cfg_path.is_file():
        print(f'ERROR: config json not found: {cfg_path}', file=sys.stderr)
        return 2

    cfg = json.loads(cfg_path.read_text(encoding='utf-8'))
    project_path = cfg.get('projectPath')
    page_url = cfg.get('pageUrl')
    if not project_path or not page_url:
        print('ERROR: comments-issue.json missing projectPath or pageUrl', file=sys.stderr)
        return 3

    # 1. Read source
    html = src_path.read_text(encoding='utf-8')

    # 2. Strip stale `<a class="discuss-btn">` markup from earlier tooling.
    html, stripped = strip_legacy_discuss_buttons(html)
    if stripped:
        print(f'OK: stripped {stripped} stale discuss-btn link(s) from source')

    # 3. Augment with ids (so anchors like #sec-4-3 resolve to the right place)
    html = ensure_heading_ids(html)
    html = add_sequential_ids(html, DIAGRAM_FRAME_RE, 'figure')
    html = add_sequential_ids(html, TABLE_WRAP_RE, 'table')

    # 4. Inject (idempotent)
    snippet = build_config_snippet(
        gitlab_host=cfg.get('gitlabHost', 'https://gitlab.aws.dev'),
        project_path=project_path,
        page_key=args.page_key,
        page_url=page_url,
        title_prefix=cfg.get('titlePrefix', '[doc-comment]'),
        issue_labels=cfg.get('issueLabels', 'doc-comments'),
    )
    html = inject_assets(html, args.assets_url, snippet)

    # 5. Write output + copy widget assets
    out_path.parent.mkdir(parents=True, exist_ok=True)
    out_path.write_text(html, encoding='utf-8')

    assets_dir.mkdir(parents=True, exist_ok=True)
    here = Path(__file__).parent
    for name in (SCRIPT_NAME, STYLE_NAME):
        shutil.copy2(here / name, assets_dir / name)

    print(f'OK: wrote {out_path} ({out_path.stat().st_size} bytes)')
    print(f'OK: copied assets to {assets_dir}/')
    return 0


if __name__ == '__main__':
    raise SystemExit(main())

#!/usr/bin/env python3
"""Validate an HTML doc before publishing.

Checks:
  1. Every tag opens and closes cleanly (simple stack-based parser).
  2. Headings have id attributes (so widget-generated anchor URLs scroll
     to the right place after submission).
  3. Counts: sections, headings, mermaid figures, tables.

Run on the source HTML before the inject step:

    python3 validate-html.py docs/v1.0.0/tech-design.html

Or on the published HTML to confirm the inject step ran:

    python3 validate-html.py public/v1.0.0/index.html
"""
import re
import sys
from html.parser import HTMLParser
from pathlib import Path


class TagBalance(HTMLParser):
    VOID = {
        "br", "hr", "meta", "link", "img", "input", "area",
        "base", "col", "embed", "source", "track", "wbr",
    }

    def __init__(self):
        super().__init__()
        self.stack = []
        self.errors = []

    def handle_starttag(self, tag, attrs):
        if tag in self.VOID:
            return
        self.stack.append(tag)

    def handle_endtag(self, tag):
        if tag in self.VOID:
            return
        if self.stack and self.stack[-1] == tag:
            self.stack.pop()
        else:
            self.errors.append(
                f"expected </{self.stack[-1] if self.stack else '?'}> got </{tag}>"
            )


HEADING_RE = re.compile(r'<(h[1-6])([^>]*)>', re.IGNORECASE)
ID_ATTR_RE = re.compile(r'\bid\s*=\s*"([^"]+)"', re.IGNORECASE)


def main():
    if len(sys.argv) < 2:
        print("Usage: validate-html.py <file.html>", file=sys.stderr)
        sys.exit(1)

    html = Path(sys.argv[1]).read_text(encoding="utf-8")
    print(f"=== {sys.argv[1]} — {len(html):,} bytes ===\n")

    # 1. Tag balance
    bal = TagBalance()
    bal.feed(html)
    if bal.errors:
        print(f"❌ Tag balance: {len(bal.errors)} errors")
        for e in bal.errors[:5]:
            print(f"   - {e}")
    else:
        print("✅ Tag balance: OK")
    if bal.stack:
        print(f"   Unclosed tags at EOF: {bal.stack[-5:]}")

    # 2. Heading id coverage
    headings = HEADING_RE.findall(html)
    headings_without_id = [
        tag for tag, attrs in headings if not ID_ATTR_RE.search(attrs)
    ]
    if headings_without_id:
        print(
            f"⚠ Heading ids: {len(headings_without_id)} of {len(headings)} "
            f"h1..h6 have no id (run inject-comments.py to add them)"
        )
    else:
        print(f"✅ Heading ids: all {len(headings)} h1..h6 have id attributes")

    # 3. Counts
    print()
    print(f"Headings (h1..h6):   {len(headings)}")
    print(f"Mermaid figures:     {html.count('<div class=\"diagram-frame\"')}")
    print(f"Tables (aws-table):  {html.count('<div class=\"aws-table-wrap\"')}")
    print(
        "Widget injected:     "
        + ("yes" if 'doc-comments-injected' in html else "no")
    )

    if bal.errors:
        sys.exit(1)


if __name__ == "__main__":
    main()

# GitLab Pages deployment template for technical design docs.
#
# What it does:
#   - Runs on every push to main
#   - Copies docs/<VERSION>/*.html → public/<VERSION>/index.html
#   - Copies companion .md files for reference
#   - Generates a simple landing index.html at project root
#
# After merge, docs are served at the project Pages URL. Check
# Settings → Pages in your GitLab project for the exact hostname.
#
# Placeholders to replace before committing:
#   <VERSION>   → e.g. v1.0.0 or latest
#   <MAIN_HTML> → e.g. tech-design.html (the main HTML doc)

pages:
  stage: deploy
  image: python:3.11-alpine
  script:
    - mkdir -p public/<VERSION>
    # Inject the selection-bubble widget + heading/figure/table ids into the
    # published HTML. Outputs index.html and copies comment-widget.{js,css}
    # into public/<VERSION>/_assets. See SKILL.md for config-json schema.
    - python3 scripts/inject-comments.py
        --html docs/<VERSION>/<MAIN_HTML>
        --out  public/<VERSION>/index.html
        --assets-dir public/<VERSION>/_assets
        --assets-url _assets
        --config-json docs/<VERSION>/comments-issue.json
        --page-key <VERSION>/<MAIN_HTML>
    - cp docs/<VERSION>/*.md public/<VERSION>/ 2>/dev/null || true
    - |
      cat > public/index.html <<'HTML'
      <!DOCTYPE html>
      <html lang="zh-CN">
      <head>
        <meta charset="UTF-8">
        <title>Project Documentation</title>
        <style>
          body { font-family: -apple-system, system-ui, 'Segoe UI', sans-serif;
                 max-width: 720px; margin: 80px auto; padding: 0 24px; color: #16191f; }
          h1 { color: #232f3e; }
          ul { line-height: 2; }
          a { color: #0972d3; text-decoration: none; }
          a:hover { text-decoration: underline; }
          .meta { color: #879596; font-size: 13px; margin-top: 24px; }
        </style>
      </head>
      <body>
        <h1>Project Documentation</h1>
        <ul>
          <li><a href="<VERSION>/"><VERSION> Technical Design</a></li>
        </ul>
        <div class="meta">Hosted on GitLab Pages · Auto-updated on push to main.</div>
      </body>
      </html>
      HTML
  artifacts:
    paths:
      - public
    expire_in: never
  # NOTE: We intentionally don't use `changes:` here. Merge-commit diffs can
  # bypass `changes:` rules, causing the Pages pipeline to skip. Trigger on
  # every main push instead — the job is cheap.
  rules:
    - if: $CI_COMMIT_BRANCH == "main"