fix: address review feedback (revert Go bump, add tests, update docs, neutralize comment)

Author: blackwell-systems

cmd/openapi/commands/openapi/README.md

@@ -1260,7 +1260,7 @@ openapi spec query --format json 'schemas | where(isComponent) | take(5)' ./spec
 
 | Flag       | Short | Description                                                     |
 | ---------- | ----- | --------------------------------------------------------------- |
-| `--format` |       | Output format: `table` (default), `json`, `markdown`, or `toon` |
+| `--format` |       | Output format: `table` (default), `json`, `markdown`, `toon`, or `gcf` |
 | `--file`   | `-f`  | Read query from file instead of argument                        |
 
 For the full query language reference, run `openapi spec query-reference`.

cmd/openapi/commands/openapi/query.go

@@ -36,7 +36,7 @@ Pipeline stages:
                group-by(field), group-by(field, name_field), length
   Variables:   let $var = expr
   Functions:   def name: body;  def name($p): body;  include "file.oq";
-  Output:      to-yaml, format(table|json|markdown|toon)
+  Output:      to-yaml, format(table|json|markdown|toon|gcf)
   Meta:        explain, fields
 
 Operators: ==, !=, >, <, >=, <=, and, or, not, // (or default), has(),

go.mod

@@ -1,9 +1,9 @@
 module github.com/speakeasy-api/openapi
 
-go 1.26.1
+go 1.25.0
 
 require (
-	github.com/blackwell-systems/gcf-go v1.2.1
+	github.com/blackwell-systems/gcf-go v1.2.2
 	github.com/santhosh-tekuri/jsonschema/v6 v6.0.2
 	github.com/speakeasy-api/jsonpath v0.6.3
 	github.com/stretchr/testify v1.11.1

go.sum

@@ -1,5 +1,5 @@
-github.com/blackwell-systems/gcf-go v1.2.1 h1:NsoGZKQxT8O3WKl+QssiFdvhPM0cCCyJ3a3x1H5fGDI=
-github.com/blackwell-systems/gcf-go v1.2.1/go.mod h1:sROSBELq+iEDf3pD1x4AcY2QccFd1KHsGajFzjVlCNc=
+github.com/blackwell-systems/gcf-go v1.2.2 h1:oPc9VbC5DDMPek/RMWO3zVcImVr3QTOcCIgBOLcjNRk=
+github.com/blackwell-systems/gcf-go v1.2.2/go.mod h1:E4fW1kxdrIoWxlI4iwZL8mh7BvdLTkE88NyijtGGcZc=
 github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=

oq/README.md

@@ -113,7 +113,7 @@ Navigate into the internal structure of operations. These stages produce new row
 |-------|-------------|
 | `explain` | Print query plan |
 | `fields` | List available fields |
-| `format(fmt)` | Set output format (table/json/markdown/toon) |
+| `format(fmt)` | Set output format (table/json/markdown/toon/gcf) |
 | `to-yaml` | Output raw YAML nodes from underlying spec objects |
 
 The `to-yaml` stage uses `path` (JSON pointer) as the wrapper key for each emitted node, giving full attribution to the source location in the spec.
@@ -349,6 +349,7 @@ openapi spec query 'schemas | take(5) | format(markdown)' spec.yaml
 | `json` | JSON array |
 | `markdown` | Markdown table |
 | `toon` | [TOON](https://github.com/toon-format/toon) tabular format |
+| `gcf` | [GCF](https://gcformat.com) pipe-delimited format with inline schemas |
 
 ## Examples
 

oq/format.go

@@ -223,8 +223,7 @@ func FormatToon(result *Result, g *graph.SchemaGraph) string {
 }
 
 // FormatGCF formats a result using GCF (Graph Compact Format).
-// GCF uses positional pipe-delimited rows with inline schemas, achieving
-// higher LLM comprehension accuracy than TOON or JSON (90.7% vs 68.5% vs 53.6%).
+// GCF uses positional pipe-delimited rows with inline schemas.
 // See https://gcformat.com
 func FormatGCF(result *Result, g *graph.SchemaGraph) string {
 	if result.Explain != "" {
@@ -399,7 +398,28 @@ func toonValue(v expr.Value) string {
 	case expr.KindBool:
 		return strconv.FormatBool(v.Bool)
 	case expr.KindArray:
-		return toonEscape(strings.Join(v.Arr, ";"))
+		hasSemicolon := false
+		for _, s := range v.Arr {
+			if strings.Contains(s, ";") {
+				hasSemicolon = true
+				break
+			}
+		}
+		if !hasSemicolon {
+			return toonEscape(strings.Join(v.Arr, ";"))
+		}
+		// Fall back to JSON array syntax when elements contain ";"
+		// to avoid ambiguity with the semicolon delimiter.
+		var sb strings.Builder
+		sb.WriteByte('[')
+		for i, s := range v.Arr {
+			if i > 0 {
+				sb.WriteByte(',')
+			}
+			fmt.Fprintf(&sb, "%q", s)
+		}
+		sb.WriteByte(']')
+		return sb.String()
 	default:
 		return "null"
 	}

oq/oq_test.go

@@ -1412,6 +1412,86 @@ func TestFormatToon_Explain(t *testing.T) {
 	assert.Contains(t, toon, "Source: schemas", "toon should render explain output")
 }
 
+func TestFormatGCF_Success(t *testing.T) {
+	t.Parallel()
+	g := loadTestGraph(t)
+
+	result, err := oq.Execute("schemas | where(isComponent) | take(3) | select name, type", g)
+	require.NoError(t, err)
+
+	out := oq.FormatGCF(result, g)
+	assert.Contains(t, out, "GCF profile=generic", "gcf should have profile header")
+	assert.Contains(t, out, "{name,type}", "gcf should declare field names")
+	assert.Contains(t, out, "object", "gcf should include object type value")
+}
+
+func TestFormatGCF_Count_Success(t *testing.T) {
+	t.Parallel()
+	g := loadTestGraph(t)
+
+	result, err := oq.Execute("schemas | length", g)
+	require.NoError(t, err)
+
+	out := oq.FormatGCF(result, g)
+	assert.Contains(t, out, "count=", "gcf count should use key=value format")
+}
+
+func TestFormatGCF_Groups_Success(t *testing.T) {
+	t.Parallel()
+	g := loadTestGraph(t)
+
+	result, err := oq.Execute("schemas | where(isComponent) | group-by(type)", g)
+	require.NoError(t, err)
+
+	out := oq.FormatGCF(result, g)
+	assert.Contains(t, out, "GCF profile=generic", "gcf should have profile header")
+	assert.Contains(t, out, "{count,key,names}", "gcf should declare group fields")
+}
+
+func TestFormatGCF_Empty_Success(t *testing.T) {
+	t.Parallel()
+	g := loadTestGraph(t)
+
+	result, err := oq.Execute(`schemas | where(isComponent) | where(name == "NonExistent")`, g)
+	require.NoError(t, err)
+
+	out := oq.FormatGCF(result, g)
+	assert.Contains(t, out, "GCF profile=generic", "empty gcf should still have profile header")
+}
+
+func TestFormatGCF_SpecialChars(t *testing.T) {
+	t.Parallel()
+	g := loadTestGraph(t)
+
+	result, err := oq.Execute("schemas | where(isComponent) | take(1) | select name, depth, isComponent", g)
+	require.NoError(t, err)
+
+	out := oq.FormatGCF(result, g)
+	assert.NotEmpty(t, out, "gcf output should not be empty")
+	assert.Contains(t, out, "GCF profile=generic", "gcf should have profile header")
+}
+
+func TestFormatGCF_Explain(t *testing.T) {
+	t.Parallel()
+	g := loadTestGraph(t)
+
+	result, err := oq.Execute("schemas | where(depth > 0) | explain", g)
+	require.NoError(t, err)
+
+	out := oq.FormatGCF(result, g)
+	assert.Contains(t, out, "Source: schemas", "gcf should render explain output as-is")
+}
+
+func TestFormatGCF_InlinePipeline(t *testing.T) {
+	t.Parallel()
+	g := loadTestGraph(t)
+
+	result, err := oq.Execute("schemas | where(isComponent) | take(3) | format(gcf)", g)
+	require.NoError(t, err)
+
+	assert.Equal(t, "gcf", result.FormatHint, "format(gcf) should set FormatHint")
+}
+
 func TestFormatMarkdown_Explain(t *testing.T) {
 	t.Parallel()
 	g := loadTestGraph(t)