larksuite-cli/cmd/service/paramhelp.go

// Copyright (c) 2026 Lark Technologies Pte. Ltd.
// SPDX-License-Identifier: MIT

// Help rendering for generated param flags. fieldFacts is the single list of
// agent-relevant facts a param exposes; every help surface (the typed flag's
// usage line, the params-only --params addendum) renders that one list, so the
// surfaces cannot drift over which facts exist. Values come from the
// meta.Field accessors, so nothing here depends on internal/schema.

package service

import (
	"fmt"
	"regexp"
	"strconv"
	"strings"

	"github.com/larksuite/cli/internal/meta"
	"github.com/larksuite/cli/internal/util"
)

// fieldFacts returns a param field's facts in display order, each as a compact
// one-line clause: the sanitized description, the allowed enum values (with
// meanings), the min/max constraint, and the API default. This is the ONE
// place that decides what a param's help says — add a fact here (e.g. a future
// deprecation marker) and every surface shows it. Unabridged prose and
// per-option detail stay in `lark-cli schema`.
func fieldFacts(f meta.Field) []string {
	var facts []string
	if d := sanitizeFieldDesc(f.Description); d != "" {
		facts = append(facts, d)
	}
	if opts := f.EnumOptions(); len(opts) > 0 {
		facts = append(facts, "enum: "+formatEnumInline(opts))
	}
	if b := formatBoundsInline(f); b != "" {
		facts = append(facts, b)
	}
	if s := literalStr(f.CoercedDefault()); s != "" {
		facts = append(facts, "API default: "+s)
	}
	return facts
}

// paramFlagUsage renders the typed param flag's help line:
//
//	<param_name>, required|optional[. <fact>]...
//
// It leads with the canonical underscore param name (the key this flag
// overrides in --params) and required/optional, then joins the field's facts
// inline.
func paramFlagUsage(f meta.Field) string {
	req := "optional"
	if f.Required {
		req = "required"
	}
	parts := append([]string{fmt.Sprintf("%s, %s", f.Name, req)}, fieldFacts(f)...)
	return strings.Join(parts, ". ") + "."
}

// paramExample picks a concrete sample for a params-only field's --help snippet:
// its first allowed enum value, else its example, else a placeholder.
func paramExample(f meta.Field) string {
	if vals := enumStrings(f.EnumValues()); len(vals) > 0 {
		return fmt.Sprintf("%q", vals[0])
	}
	if s := literalStr(f.CoercedExample()); s != "" {
		return fmt.Sprintf("%q", s)
	}
	return `"<value>"`
}

var markdownLinkRe = regexp.MustCompile(`\[([^\]]*)\]\([^)]*\)`)

// inlineClause compresses metadata prose into one help clause: markdown links
// keep their text, the clause cuts at the first rune in stops, whitespace
// collapses, trailing punctuation goes — sentence enders (the clause join adds
// its own) and connectors a cut can strand, like a colon introducing a list the
// newline cut dropped — and the result caps at max runes. The two policies
// below differ only in where they cut and how much they keep.
func inlineClause(s, stops string, max int) string {
	if s == "" {
		return ""
	}
	s = markdownLinkRe.ReplaceAllString(s, "$1")
	// Backquotes must go: pflag's UnquoteUsage treats a backquoted word in a
	// flag's usage string as the flag's metavar, so a description like wiki
	// space_id's "可替换为`my_library`" would render the flag as
	// "--space-id my_library" instead of "--space-id string".
	s = strings.ReplaceAll(s, "`", "")
	if i := strings.IndexAny(s, stops); i >= 0 {
		s = s[:i]
	}
	s = strings.Join(strings.Fields(s), " ")
	s = strings.TrimRight(s, "。.：:，,、")
	return util.TruncateStrWithEllipsis(s, max)
}

// sanitizeOptionDesc is the enum-option policy: many values share one line, so
// keep only the first clause (cut at 。 too) and stay ultra-compact.
func sanitizeOptionDesc(s string) string { return inlineClause(s, "。；;\n\r", 40) }

// sanitizeFieldDesc is the field-description policy: one line per field, so
// keep full sentences and cut only at note separators (meta_data appends
// bullet notes after ;/；) — the later sentence often carries the key
// affordance, e.g. user_mailbox_id's `可以输入"me"`.
func sanitizeFieldDesc(s string) string { return inlineClause(s, "；;\n\r", 60) }

// formatEnumInline renders allowed values for the help line: "v=meaning" when
// the value carries a (sanitized, truncated) description — so opaque numeric
// enums like succeed_type read as "0=…|1=…|2=…" — else just "v". Full meanings
// live in the envelope's enumDescriptions / `lark-cli schema`.
func formatEnumInline(opts []meta.EnumOption) string {
	items := make([]string, len(opts))
	for i, o := range opts {
		if d := sanitizeOptionDesc(o.Description); d != "" {
			items[i] = fmt.Sprintf("%v=%s", o.Value, d)
		} else {
			items[i] = fmt.Sprintf("%v", o.Value)
		}
	}
	return strings.Join(items, "|")
}

// formatBoundsInline renders the field's min/max constraint ("min: 1, max:
// 100", or the single declared side), or "" when the field declares neither.
// The vocabulary matches the envelope's minimum/maximum, so help and `lark-cli
// schema` state the same constraint.
func formatBoundsInline(f meta.Field) string {
	min, max := f.MinBound(), f.MaxBound()
	switch {
	case min != nil && max != nil:
		return fmt.Sprintf("min: %s, max: %s", formatBound(*min), formatBound(*max))
	case min != nil:
		return "min: " + formatBound(*min)
	case max != nil:
		return "max: " + formatBound(*max)
	}
	return ""
}

// formatBound renders a bound without a float artifact (100 not 100.000000).
func formatBound(v float64) string {
	return strconv.FormatFloat(v, 'f', -1, 64)
}

// literalStr renders a coerced literal (default/example) for flag help,
// returning "" for a nil or empty value so the caller can omit the clause.
func literalStr(v interface{}) string {
	if v == nil {
		return ""
	}
	return fmt.Sprintf("%v", v)
}

func enumStrings(enum []interface{}) []string {
	out := make([]string, 0, len(enum))
	for _, e := range enum {
		out = append(out, fmt.Sprintf("%v", e))
	}
	return out
}