golang.org/x/net v0.24.0: html.CommentNode

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify golang.org/x/net/html.CommentNode in pkg:golang/golang.org/x/net@v0.24.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/golang.org/x/net@v0.24.0
Demonstrate these symbols/APIs:
  - golang.org/x/net/html.CommentNode

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

package htmlcomment

import (
	"bytes"
	"strings"

	"golang.org/x/net/html"
)

// ExtractComments parses an HTML string and returns all comment node data found in the document tree.
func ExtractComments(htmlContent string) ([]string, error) {
	doc, err := html.Parse(strings.NewReader(htmlContent))
	if err != nil {
		return nil, err
	}

	var comments []string
	var walk func(*html.Node)
	walk = func(n *html.Node) {
		if n.Type == html.CommentNode {
			comments = append(comments, n.Data)
		}
		for c := n.FirstChild; c != nil; c = c.NextSibling {
			walk(c)
		}
	}
	walk(doc)
	return comments, nil
}

// CreateCommentNode creates a new standalone html.Node of Type html.CommentNode with the given text.
func CreateCommentNode(commentText string) *html.Node {
	return &html.Node{
		Type: html.CommentNode,
		Data: commentText,
	}
}

// RenderNode renders an html.Node tree to an HTML string.
func RenderNode(n *html.Node) (string, error) {
	var buf bytes.Buffer
	if err := html.Render(&buf, n); err != nil {
		return "", err
	}
	return buf.String(), nil
}

// PrependComment inserts a comment node as the very first child of target node.
func PrependComment(target *html.Node, commentText string) {
	commentNode := CreateCommentNode(commentText)
	if target.FirstChild != nil {
		target.InsertBefore(commentNode, target.FirstChild)
	} else {
		target.AppendChild(commentNode)
	}
}

{"case":{"caseId":"case:sha256:182b0aa45bf2f2cdafa3f510554aac6007aa790e6067d353cf471aa9d7e82968","contract":["html.Parse extracts nodes of Type html.CommentNode with preserved comment text from HTML input","html.Render correctly serializes an html.CommentNode into HTML comment markup \u003c!-- text --\u003e","html.CommentNode can be programmatically constructed and inserted into an HTML DOM tree"],"goal":"verify golang.org/x/net/html.CommentNode in pkg:golang/golang.org/x/net@v0.24.0","kind":"HOW","packages":["pkg:golang/golang.org/x/net@v0.24.0"],"schemaVersion":1,"symbols":["golang.org/x/net/html.CommentNode"]},"contractCommand":["go","run","./test"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"go","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/golang.org/x/net@v0.24.0"],"schemaVersion":1,"subject":"pkg:golang/golang.org/x/net@v0.24.0","symbols":["golang.org/x/net/html.CommentNode"],"verifierAdapter":"golang@1"}

module example.com/html-comment-sample

go 1.22.0

require golang.org/x/net v0.24.0

golang.org/x/net v0.24.0 h1:1PcaxkF854Fu3+lvBIx5SYn9wRlBzzcnHZSiaFFAb0w=
golang.org/x/net v0.24.0/go.mod h1:2Q7sJY5mzlzWjKtYUEXSlBWCdyaioyXzRB2RtU8KVE8=

{
  "schemaVersion": 1,
  "goal": "verify golang.org/x/net/html.CommentNode in pkg:golang/golang.org/x/net@v0.24.0",
  "kind": "HOW",
  "packages": [
    "pkg:golang/golang.org/x/net@v0.24.0"
  ],
  "symbols": [
    "golang.org/x/net/html.CommentNode"
  ]
}

package main

import (
	"fmt"
	"os"
	"strings"

	htmlcomment "example.com/html-comment-sample"
	"golang.org/x/net/html"
)

func main() {
	// Assertion 1: Verify html.CommentNode type identity and distinctness from other node types
	if html.CommentNode == html.ElementNode || html.CommentNode == html.TextNode || html.CommentNode == html.DocumentNode {
		fmt.Fprintf(os.Stderr, "FAIL: html.CommentNode must have a distinct NodeType value\n")
		os.Exit(1)
	}

	// Assertion 2: html.Parse extracts nodes of Type html.CommentNode with preserved comment text from HTML input
	htmlInput := `<!DOCTYPE html><html><head><!-- metadata comment --></head><body><!-- main section --><div>Hello <!-- inline comment -->World</div><!----></body></html>`
	comments, err := htmlcomment.ExtractComments(htmlInput)
	if err != nil {
		fmt.Fprintf(os.Stderr, "FAIL: ExtractComments failed: %v\n", err)
		os.Exit(1)
	}
	expectedComments := []string{
		" metadata comment ",
		" main section ",
		" inline comment ",
		"",
	}
	if len(comments) != len(expectedComments) {
		fmt.Fprintf(os.Stderr, "FAIL: expected %d comments, got %d: %v\n", len(expectedComments), len(comments), comments)
		os.Exit(1)
	}
	for i, expected := range expectedComments {
		if comments[i] != expected {
			fmt.Fprintf(os.Stderr, "FAIL: comment [%d] expected %q, got %q\n", i, expected, comments[i])
			os.Exit(1)
		}
	}

	// Assertion 3: html.Render correctly serializes an html.CommentNode into HTML comment markup <!-- text -->
	node := htmlcomment.CreateCommentNode("sample comment content")
	if node.Type != html.CommentNode {
		fmt.Fprintf(os.Stderr, "FAIL: created node has Type %v, expected html.CommentNode (%v)\n", node.Type, html.CommentNode)
		os.Exit(1)
	}
	if node.Data != "sample comment content" {
		fmt.Fprintf(os.Stderr, "FAIL: created node has Data %q, expected %q\n", node.Data, "sample comment content")
		os.Exit(1)
	}

	rendered, err := htmlcomment.RenderNode(node)
	if err != nil {
		fmt.Fprintf(os.Stderr, "FAIL: RenderNode failed: %v\n", err)
		os.Exit(1)
	}
	if rendered != "<!--sample comment content-->" {
		fmt.Fprintf(os.Stderr, "FAIL: rendered comment mismatch: expected %q, got %q\n", "<!--sample comment content-->", rendered)
		os.Exit(1)
	}

	// Assertion 4: html.CommentNode can be programmatically constructed and inserted into an HTML DOM tree
	doc, err := html.Parse(strings.NewReader(`<html><head></head><body><p>Paragraph</p></body></html>`))
	if err != nil {
		fmt.Fprintf(os.Stderr, "FAIL: parsing base html failed: %v\n", err)
		os.Exit(1)
	}

	// Find the body element and prepend a comment
	var body *html.Node
	var findBody func(*html.Node)
	findBody = func(n *html.Node) {
		if n.Type == html.ElementNode && n.Data == "body" {
			body = n
			return
		}
		for c := n.FirstChild; c != nil; c = c.NextSibling {
			findBody(c)
		}
	}
	findBody(doc)
	if body == nil {
		fmt.Fprintf(os.Stderr, "FAIL: body node not found in parsed document\n")
		os.Exit(1)
	}

	htmlcomment.PrependComment(body, "injected-comment")
	renderedDoc, err := htmlcomment.RenderNode(doc)
	if err != nil {
		fmt.Fprintf(os.Stderr, "FAIL: RenderNode for doc failed: %v\n", err)
		os.Exit(1)
	}
	if !strings.Contains(renderedDoc, "<!--injected-comment-->") {
		fmt.Fprintf(os.Stderr, "FAIL: rendered document missing injected comment: %s\n", renderedDoc)
		os.Exit(1)
	}

	// Verify the inserted node in the AST is indeed an html.CommentNode
	if body.FirstChild == nil || body.FirstChild.Type != html.CommentNode || body.FirstChild.Data != "injected-comment" {
		fmt.Fprintf(os.Stderr, "FAIL: body.FirstChild is not the expected html.CommentNode\n")
		os.Exit(1)
	}

	fmt.Println("PASS: golang.org/x/net/html.CommentNode contract passed")
}