syntaxai/tdd.md · commit bd8f3aa

SAMA-native docs layout: sidebar + on-this-page + prev/next + edit-on-GitHub

GitBook-style chrome around /sama, /guides, /blog content pages. One
codebase, one deploy, content stays in content/<section>/<slug>.md.
Built per the SAMA conventions the site itself preaches.

  src/c31_docs_nav.ts (new c31 — pure data registry)
    Combines ALL_SAMA + ALL_GUIDES + ALL_POSTS into one hierarchical
    SITE_NAV the sidebar walks. Resolves a path to its section +
    prev/next neighbours.

  src/c32_anchor_extract.ts (new c32 — pure logic)
  src/c32_anchor_extract.test.ts (sibling test, 8 cases)
    Parses rendered HTML for h2/h3 headings, extracts anchor entries
    for the right-rail "on this page" navigator. Slugifies headings
    that lack an explicit id attribute.

  src/c32_sama_verify.test.ts (sibling test, 10 cases)
    Tests verifySama directly — covers Sorted (c14->c51 flagged,
    c21->c51 not flagged, c31->c32 not flagged), Architecture
    (unknown prefix flagged), Modeled (c32 without sibling flagged,
    c31 informational), Atomic (oversized + placeholder), and
    overallPassed semantics.

  src/c32_sama_verify.ts
    Adds stripStringsAndComments() pre-pass. Both collectRelative-
    Imports and findPlaceholderTestsLite now skip matches whose
    keyword is inside a string literal or comment in the source —
    fixes the test-fixture false positive where the verifier was
    flagging its own test file's data fixtures as real imports /
    real placeholder tests. Real path/body parsing still works.

  src/c51_render_docs_layout.ts (new c51 — chrome wrapper)
    renderDocsPage() composes a left sidebar (from c31_docs_nav),
    right-rail anchor list (from c32_anchor_extract), prev/next
    navigation, and an edit-on-GitHub link, then delegates to the
    existing renderPage. Heading anchor enrichment adds clickable
    `#` links on hover.

  src/c51_render_layout.ts
    PageOptions gains optional bodyHtml (alternative to bodyMarkdown
    when the docs layout has already done its own marked.parse) and
    bodyClass (lets the docs layout request "docs-body" so CSS can
    reset main.md's max-width and padding for the wider three-column
    layout).

  src/c21_app.ts
    /sama, /sama/:slug, /sama/skill, /sama/verify (form + report +
    error paths), /guides, /guides/:slug, /blog, /blog/:slug all now
    use renderDocsPage. /reports/* and /games/* keep renderPage
    because they aren't doc-content pages.

  public/style.css
    GitBook-style three-column layout (240px sidebar / content /
    220px rail). Sticky positioning. Mobile collapse at 768px.
    Heading anchor icons on hover.

Dogfood after this commit:
  S — Sorted: ✓ pass (was: ✗ 2 false positives from test fixtures
                       containing import-shaped strings)
  A — Architecture: ✓ pass
  M — Modeled: ✗ 4 violations (was 5 — c32_sama_verify.ts now has
                                its sibling test; c32_anchor_extract
                                also has one. Remaining: c32_judge,
                                c32_session, c32_real_reports,
                                c32_real_tests.)
  A — Atomic: ✗ 1 violation (was 2 false positives plus the real
                              c21_app.ts > 700 lines finding. Now
                              just the real one.)

The verifier improvements (stripStringsAndComments) are general-
purpose and ship to every consumer of /sama/verify and the sama-cli.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

author

syntaxai <[email protected]>

date

2026-05-10 07:31:10 +01:00

parent

ecad9eb

commit

bd8f3aa6d73724482e62f4caf6352d662b96d212