|
| 1 | +package docsgen |
| 2 | + |
| 3 | +import ( |
| 4 | + "encoding/json" |
| 5 | + "fmt" |
| 6 | + "os" |
| 7 | + "path/filepath" |
| 8 | + "strings" |
| 9 | +) |
| 10 | + |
| 11 | +// declarationField mirrors one entry of |
| 12 | +// frontend/src/atlas/atlasNounDeclarationFields.json -- the noun |
| 13 | +// registry contract table's own source data (goal 0211). Go has no |
| 14 | +// TypeScript parser, so extracting the table straight from |
| 15 | +// AtlasToolShape's own .ts declaration was disproportionate; this JSON |
| 16 | +// is the generation source instead, and |
| 17 | +// atlasNounDeclarationFields.test.ts is the other half of the |
| 18 | +// freshness chain, `satisfies`-checking a literal field-key list |
| 19 | +// against the real type at TS compile time and comparing this JSON's |
| 20 | +// own field set against that list at test time. Neither half alone |
| 21 | +// would catch drift on its own language's side. |
| 22 | +type declarationField struct { |
| 23 | + Field string `json:"field"` |
| 24 | + LegalValues string `json:"legalValues"` |
| 25 | + Meaning string `json:"meaning"` |
| 26 | +} |
| 27 | + |
| 28 | +// Markers bounding the one generated region inside the otherwise |
| 29 | +// hand-authored userdocs/reference/extending-the-canvas.md -- naming |
| 30 | +// the exact source keeps the page honest about what freshness is (and |
| 31 | +// is not) enforced: only the region between these two lines is |
| 32 | +// regenerated by `go generate ./internal/docsgen` and diff-checked by |
| 33 | +// TestExtendingCanvasPage_NounFieldTableMatchesCommitted; the prose |
| 34 | +// around it carries no such promise. |
| 35 | +const ( |
| 36 | + NounFieldTableBeginMarker = "<!-- BEGIN GENERATED: noun declaration fields (source: frontend/src/atlas/atlasNounDeclarationFields.json) -->" |
| 37 | + NounFieldTableEndMarker = "<!-- END GENERATED -->" |
| 38 | +) |
| 39 | + |
| 40 | +// GenerateNounFieldTable renders every AtlasToolShape declaration |
| 41 | +// field as a markdown table, read from the committed JSON at |
| 42 | +// <frontendAtlasDir>/atlasNounDeclarationFields.json. `commit` is |
| 43 | +// skipped -- it is the one AtlasToolShape member that is runtime code, |
| 44 | +// not inert declaration, and the page's "How it loads" section |
| 45 | +// documents it separately under the declaration-vs-code split. |
| 46 | +func GenerateNounFieldTable(frontendAtlasDir string) (string, error) { |
| 47 | + raw, err := os.ReadFile(filepath.Join(frontendAtlasDir, "atlasNounDeclarationFields.json")) // #nosec G304 -- caller-controlled fixed path, never external input |
| 48 | + if err != nil { |
| 49 | + return "", fmt.Errorf("read atlasNounDeclarationFields.json: %w", err) |
| 50 | + } |
| 51 | + var fields []declarationField |
| 52 | + if err := json.Unmarshal(raw, &fields); err != nil { |
| 53 | + return "", fmt.Errorf("parse atlasNounDeclarationFields.json: %w", err) |
| 54 | + } |
| 55 | + var b strings.Builder |
| 56 | + b.WriteString("| Field | Legal values | Meaning |\n") |
| 57 | + b.WriteString("|---|---|---|\n") |
| 58 | + for _, f := range fields { |
| 59 | + if f.Field == "commit" { |
| 60 | + continue |
| 61 | + } |
| 62 | + fmt.Fprintf(&b, "| `%s` | %s | %s |\n", f.Field, f.LegalValues, f.Meaning) |
| 63 | + } |
| 64 | + return b.String(), nil |
| 65 | +} |
| 66 | + |
| 67 | +// ReplaceMarkedRegion swaps the text strictly between beginMarker and |
| 68 | +// endMarker (both kept, byte-identical, in doc) for replacement -- |
| 69 | +// gen/main.go uses this to regenerate extending-the-canvas.md's one |
| 70 | +// generated table in place without touching the hand-authored prose |
| 71 | +// around it; the freshness test below does the same splice to compare |
| 72 | +// against the committed file. |
| 73 | +func ReplaceMarkedRegion(doc, beginMarker, endMarker, replacement string) (string, error) { |
| 74 | + start := strings.Index(doc, beginMarker) |
| 75 | + if start == -1 { |
| 76 | + return "", fmt.Errorf("begin marker %q not found", beginMarker) |
| 77 | + } |
| 78 | + contentStart := start + len(beginMarker) |
| 79 | + end := strings.Index(doc[contentStart:], endMarker) |
| 80 | + if end == -1 { |
| 81 | + return "", fmt.Errorf("end marker %q not found after begin marker", endMarker) |
| 82 | + } |
| 83 | + end += contentStart |
| 84 | + return doc[:contentStart] + "\n\n" + replacement + "\n" + doc[end:], nil |
| 85 | +} |
0 commit comments