feat(fn): add --help, --doc, and standalone file mode to AsMain

.gitignore

@@ -9,3 +9,6 @@ ts/create-kpt-functions/bin
 *.swo
 *.swp
 
+# rapid property-based testing failure reproductions
+**/testdata/rapid/
+

go/fn/go.mod

@@ -45,4 +45,5 @@ require (
 	google.golang.org/protobuf v1.36.10 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 	k8s.io/kube-openapi v0.0.0-20250910181357-589584f1c912 // indirect
+	pgregory.net/rapid v1.3.0 // indirect
 )

go/fn/go.sum

@@ -113,6 +113,8 @@ k8s.io/klog/v2 v2.130.1 h1:n9Xl7H1Xvksem4KFG4PYbdQCQxqc/tTUyrgXaOhHSzk=
 k8s.io/klog/v2 v2.130.1/go.mod h1:3Jpz1GvMt720eyJH1ckRHK1EDfpxISzJ7I9OYgaDtPE=
 k8s.io/kube-openapi v0.0.0-20250910181357-589584f1c912 h1:Y3gxNAuB0OBLImH611+UDZcmKS3g6CthxToOb37KgwE=
 k8s.io/kube-openapi v0.0.0-20250910181357-589584f1c912/go.mod h1:kdmbQkyfwUagLfXIad1y2TdrjPFWp2Q89B3qkRwf/pQ=
+pgregory.net/rapid v1.3.0 h1:vBvO0VSqti75J1jjYqpgPNBLKMd1+gxa9fYo7vk/Exc=
+pgregory.net/rapid v1.3.0/go.mod h1:dPlE4OBBxgXPqkP79flB6sJL1dx5azpI7HQ9MY9Z7uk=
 sigs.k8s.io/json v0.0.0-20241014173422-cfa47c3a1cc8 h1:gBQPwqORJ8d8/YNZWEjoZs7npUVDpVXUUOFfW6CgAqE=
 sigs.k8s.io/json v0.0.0-20241014173422-cfa47c3a1cc8/go.mod h1:mdzfpAEoE6DHQEN0uh9ZbOCuHbLK5wOm7dK4ctXE9Tg=
 sigs.k8s.io/kustomize/kyaml v0.20.1 h1:PCMnA2mrVbRP3NIB6v9kYCAc38uvFLVs8j/CD567A78=

go/fn/internal/docs/markers.go

@@ -0,0 +1,82 @@
+// Copyright 2026 The kpt Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package docs
+
+import "strings"
+
+// Sections holds parsed README marker content.
+type Sections struct {
+	Short    string
+	Long     string
+	Examples string
+}
+
+const (
+	markerShort    = "<!--mdtogo:Short-->"
+	markerLong     = "<!--mdtogo:Long-->"
+	markerExamples = "<!--mdtogo:Examples-->"
+	markerEnd      = "<!--mdtogo-->"
+)
+
+// ParseMarkers extracts mdtogo marker sections from README content.
+// Missing markers result in empty strings for the corresponding sections.
+// When no markers are present at all, the full content (trimmed) is returned
+// as the Long description.
+func ParseMarkers(readme []byte) Sections {
+	content := string(readme)
+
+	short := extractSection(content, markerShort)
+	long := extractSection(content, markerLong)
+	examples := extractSection(content, markerExamples)
+
+	// Fallback: if no markers are present at all, use full content as Long.
+	if !hasAnyMarker(content) {
+		return Sections{
+			Long: strings.TrimSpace(content),
+		}
+	}
+
+	return Sections{
+		Short:    short,
+		Long:     long,
+		Examples: examples,
+	}
+}
+
+// extractSection finds text between the given start marker and the next
+// <!--mdtogo--> end marker. Returns empty string if either marker is missing.
+func extractSection(content, startMarker string) string {
+	startIdx := strings.Index(content, startMarker)
+	if startIdx < 0 {
+		return ""
+	}
+	afterStart := startIdx + len(startMarker)
+	remaining := content[afterStart:]
+
+	before, _, ok := strings.Cut(remaining, markerEnd)
+	if !ok {
+		return ""
+	}
+
+	return strings.TrimSpace(before)
+}
+
+// hasAnyMarker reports whether the content contains any mdtogo marker.
+func hasAnyMarker(content string) bool {
+	return strings.Contains(content, markerShort) ||
+		strings.Contains(content, markerLong) ||
+		strings.Contains(content, markerExamples) ||
+		strings.Contains(content, markerEnd)
+}

go/fn/internal/docs/markers_test.go

@@ -0,0 +1,119 @@
+// Copyright 2026 The kpt Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package docs
+
+import (
+	"fmt"
+	"strings"
+	"testing"
+
+	"pgregory.net/rapid"
+)
+
+// Feature: sdk-alignment, Property 1: Marker parser round-trip
+//
+// For any three strings (short, long, examples), formatting them into a README
+// with mdtogo markers and then parsing that README with ParseMarkers SHALL
+// produce a Sections struct with fields equal to the original strings (after trimming).
+//
+// Validates: Requirements 6.1, 6.2, 6.3, 6.5, 5.2
+
+// genSectionContent generates arbitrary non-empty strings that do not contain
+// mdtogo markers (which would confuse the parser).
+func genSectionContent() *rapid.Generator[string] {
+	return rapid.Custom(func(t *rapid.T) string {
+		s := rapid.StringMatching(`[a-zA-Z0-9 \t\n.,;:!?(){}\[\]'"/_-]{1,200}`).Draw(t, "content")
+		// Ensure the generated content does not accidentally contain marker strings.
+		s = strings.ReplaceAll(s, "<!--mdtogo:", "")
+		s = strings.ReplaceAll(s, "<!--", "")
+		return s
+	})
+}
+
+// formatMarkedREADME formats three section strings into a README with mdtogo markers.
+func formatMarkedREADME(short, long, examples string) string {
+	return fmt.Sprintf(`<!--mdtogo:Short-->
+%s
+<!--mdtogo-->
+
+<!--mdtogo:Long-->
+%s
+<!--mdtogo-->
+
+<!--mdtogo:Examples-->
+%s
+<!--mdtogo-->
+`, short, long, examples)
+}
+
+// Feature: sdk-alignment, Property 7: Missing markers fallback
+//
+// For any README content that does NOT contain mdtogo markers, ParseMarkers
+// SHALL return empty strings for Short and Examples, and the full content
+// (trimmed) as Long.
+//
+// Validates: Requirements 5.4, 6.4
+
+// genNoMarkerContent generates arbitrary strings guaranteed not to contain
+// any mdtogo marker substrings.
+func genNoMarkerContent() *rapid.Generator[string] {
+	return rapid.Custom(func(t *rapid.T) string {
+		s := rapid.StringMatching(`[a-zA-Z0-9 \t\n.,;:!?(){}\[\]'"/_-]{0,300}`).Draw(t, "content")
+		// Strip anything that could form a marker.
+		s = strings.ReplaceAll(s, "<!--mdtogo:", "")
+		s = strings.ReplaceAll(s, "<!--mdtogo", "")
+		s = strings.ReplaceAll(s, "<!--", "")
+		return s
+	})
+}
+
+func TestProperty7_MissingMarkersFallback(t *testing.T) {
+	rapid.Check(t, func(t *rapid.T) {
+		content := genNoMarkerContent().Draw(t, "readme")
+
+		sections := ParseMarkers([]byte(content))
+
+		if sections.Short != "" {
+			t.Fatalf("Short should be empty for content without markers, got: %q", sections.Short)
+		}
+		if sections.Examples != "" {
+			t.Fatalf("Examples should be empty for content without markers, got: %q", sections.Examples)
+		}
+		if got, want := sections.Long, strings.TrimSpace(content); got != want {
+			t.Fatalf("Long mismatch:\n  got:  %q\n  want: %q", got, want)
+		}
+	})
+}
+
+func TestProperty1_MarkerParserRoundTrip(t *testing.T) {
+	rapid.Check(t, func(t *rapid.T) {
+		short := genSectionContent().Draw(t, "short")
+		long := genSectionContent().Draw(t, "long")
+		examples := genSectionContent().Draw(t, "examples")
+
+		readme := formatMarkedREADME(short, long, examples)
+		sections := ParseMarkers([]byte(readme))
+
+		if got, want := sections.Short, strings.TrimSpace(short); got != want {
+			t.Fatalf("Short mismatch:\n  got:  %q\n  want: %q", got, want)
+		}
+		if got, want := sections.Long, strings.TrimSpace(long); got != want {
+			t.Fatalf("Long mismatch:\n  got:  %q\n  want: %q", got, want)
+		}
+		if got, want := sections.Examples, strings.TrimSpace(examples); got != want {
+			t.Fatalf("Examples mismatch:\n  got:  %q\n  want: %q", got, want)
+		}
+	})
+}

go/fn/internal/docs/metadata.go

@@ -0,0 +1,39 @@
+// Copyright 2026 The kpt Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package docs
+
+import "go.yaml.in/yaml/v3"
+
+// Metadata holds parsed metadata.yaml content.
+type Metadata struct {
+	Image              string   `yaml:"image" json:"image"`
+	Description        string   `yaml:"description" json:"description"`
+	Tags               []string `yaml:"tags" json:"tags"`
+	SourceURL          string   `yaml:"sourceURL" json:"sourceURL"`
+	ExamplePackageURLs []string `yaml:"examplePackageURLs" json:"examplePackageURLs"`
+	License            string   `yaml:"license" json:"license"`
+	Hidden             bool     `yaml:"hidden" json:"hidden"`
+}
+
+// ParseMetadata parses metadata.yaml content into a Metadata struct.
+// Returns zero-value Metadata and an error if YAML is invalid.
+// Returns successfully with partial fields if optional fields are missing.
+func ParseMetadata(meta []byte) (Metadata, error) {
+	var m Metadata
+	if err := yaml.Unmarshal(meta, &m); err != nil {
+		return Metadata{}, err
+	}
+	return m, nil
+}