Skip to content

Commit a747eee

Browse files
fredbiclaude
andcommitted
refact(parsers): read the annotation line instead of matching it
The annotation classifiers asked one question — does this comment line START with a `swagger:` marker, after the noise a comment line may carry — and asked it with expressions dense enough that the rules had to be restated in prose beside them. They are string searches now, one function per rule, with the prose on the function it belongs to. There is no speed case; a full comment walk over the corpus costs hundredths of a second either way. The rules are unchanged: leading noise is spaces, tabs, `/`, `*`, `-` and at most one markdown table pipe; a name is a letter and at least one further character, so a package-qualified one is reported rather than dropped; a bare marker is told apart from no marker; `swagger:parameters` classifies any non-empty argument and leaves the shape to the grammar. Equivalence is checked rather than asserted. The retired expressions live on in the test as the specification being reproduced, and every classifier is compared against its own — verdict and capture — over a quarter of a million generated lines and a fuzz target seeded from them. That comparison found one difference, kept on purpose and covered by its own test: the old pattern could start an argument ON a space separator, because `\S` excludes the ASCII whitespace characters and nothing else, so a non-breaking space passed it. An argument now begins where the separators end, or there is none. The path annotations keep their expressions. They match a method, a path, optional tags and an operationId in sequence and are read back by submatch index, which is what patterns are for. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
1 parent 7315979 commit a747eee

6 files changed

Lines changed: 554 additions & 121 deletions

File tree

‎.claude/CLAUDE.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,8 @@ for the grammar parser and its satellite helpers.
5353
| File | Contents |
5454
|------|----------|
5555
| `matchers.go` | `ExtractAnnotation`, `ModelOverride`, `ResponseOverride`, `ParametersOverride` — the scanner-level annotation classifiers |
56-
| `regexprs.go` | Regex definitions backing the matchers + `rxRoute` / `rxOperation` for the path-annotation parsers |
56+
| `annotation_line.go` | The string-scanning primitives behind the matchers — comment-prefix stripping, keyword and argument extraction. No regexes |
57+
| `regexprs.go` | `rxRoute` / `rxOperation` (+ their heads) for the path-annotation parsers — the only regexes left in the codebase |
5758
| `parsed_path_content.go` | `ParsedPathContent` + `ParseOperationPathAnnotation` / `ParseRoutePathAnnotation` |
5859

5960
**Subpackages**
Lines changed: 217 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,217 @@
1+
// SPDX-FileCopyrightText: Copyright 2015-2025 go-swagger maintainers
2+
// SPDX-License-Identifier: Apache-2.0
3+
4+
package parsers
5+
6+
import (
7+
"strings"
8+
"unicode"
9+
"unicode/utf8"
10+
)
11+
12+
// Scanning one comment line for an annotation.
13+
//
14+
// These are string searches for what were regular expressions until this file replaced them. The
15+
// rules they enforce are unchanged and are stated on each function; the reason for spelling them
16+
// out is that they are rules about where a keyword sits on a line, and reading them off a
17+
// character walk is easier than reading them off a pattern.
18+
19+
// annotationKeyword prefixes every annotation.
20+
const annotationKeyword = "swagger:"
21+
22+
// isCommentNoise reports whether r may precede an annotation as leading noise: a Unicode space
23+
// separator, a tab, or one of the comment / list decorations `/`, `*`, `-`.
24+
func isCommentNoise(r rune) bool {
25+
switch r {
26+
case '\t', '/', '*', '-':
27+
return true
28+
default:
29+
return unicode.Is(unicode.Zs, r)
30+
}
31+
}
32+
33+
// isSpaceSeparator reports whether r is a Unicode space separator (which a tab is not).
34+
func isSpaceSeparator(r rune) bool { return unicode.Is(unicode.Zs, r) }
35+
36+
// isNameRune reports whether r may appear in an annotation keyword or in an override name after
37+
// its first character: a letter, a digit, a dash or a connector (`_`).
38+
func isNameRune(r rune) bool {
39+
return unicode.IsLetter(r) || unicode.IsNumber(r) ||
40+
unicode.Is(unicode.Pd, r) || unicode.Is(unicode.Pc, r)
41+
}
42+
43+
// isASCIISpace reports whether r is one of the characters a regexp `\S` excludes.
44+
//
45+
// Deliberately not unicode.IsSpace: the argument matchers below reject a line whose argument starts
46+
// with one of exactly these, and widening that would classify lines the previous rule did not.
47+
func isASCIISpace(r rune) bool {
48+
switch r {
49+
case '\t', '\n', '\f', '\r', ' ':
50+
return true
51+
default:
52+
return false
53+
}
54+
}
55+
56+
// afterCommentNoise returns the offset at which an annotation would have to start on line.
57+
//
58+
// It skips the leading run of comment noise, then AT MOST ONE markdown table pipe, then a further
59+
// run of space separators.
60+
//
61+
// Annotations must START the comment line: any prose before the keyword disqualifies the line, so
62+
// an annotation mentioned mid-sentence is not classified as one. The sole exception is
63+
// `swagger:route`, which may follow a single godoc identifier — that allowance lives in the path
64+
// annotation matchers (see rxRoutePrefix), not here.
65+
func afterCommentNoise(line string) int {
66+
i := skipRunes(line, 0, isCommentNoise)
67+
if i < len(line) && line[i] == '|' {
68+
i = skipRunes(line, i+1, isSpaceSeparator)
69+
}
70+
71+
return i
72+
}
73+
74+
// skipRunes returns the offset of the first rune at or after i that keep rejects.
75+
func skipRunes(s string, i int, keep func(rune) bool) int {
76+
for i < len(s) {
77+
r, size := utf8.DecodeRuneInString(s[i:])
78+
if !keep(r) {
79+
return i
80+
}
81+
i += size
82+
}
83+
84+
return i
85+
}
86+
87+
// annotationTail returns what follows `swagger:<keyword>` when line starts with that annotation,
88+
// leading comment noise aside.
89+
func annotationTail(line, keyword string) (string, bool) {
90+
rest := line[afterCommentNoise(line):]
91+
marker := annotationKeyword + keyword
92+
if !strings.HasPrefix(rest, marker) {
93+
return "", false
94+
}
95+
96+
return rest[len(marker):], true
97+
}
98+
99+
// overrideName reads the OPTIONAL name argument of a single-name struct marker on line.
100+
//
101+
// The shape is: the marker starting the line, space separators, an optional name, an optional
102+
// trailing period (a marker written as the last word of a godoc sentence), and nothing else. A
103+
// name is a letter followed by at least one further name character — a single letter is not a
104+
// name, and neither is anything package-qualified, which is what makes MalformedModelName /
105+
// MalformedResponseName able to report it instead of the marker being dropped in silence.
106+
//
107+
// wildcard admits `*` as a name, the shared-namespace synonym for the bare form that
108+
// `swagger:response` accepts.
109+
//
110+
// Returns ("", true) for a bare marker, so callers can tell "no marker" from "marker, no argument".
111+
func overrideName(line, keyword string, wildcard bool) (string, bool) {
112+
tail, ok := annotationTail(line, keyword)
113+
if !ok {
114+
return "", false
115+
}
116+
117+
arg := strings.TrimSuffix(strings.TrimLeftFunc(tail, isSpaceSeparator), ".")
118+
switch {
119+
case arg == "":
120+
return "", true // bare marker
121+
case wildcard && arg == "*":
122+
return arg, true
123+
case isOverrideName(arg):
124+
return arg, true
125+
default:
126+
return "", false
127+
}
128+
}
129+
130+
// isOverrideName reports whether s is a plain identifier-shaped name: a letter, then at least one
131+
// further name character.
132+
func isOverrideName(s string) bool {
133+
first, size := utf8.DecodeRuneInString(s)
134+
if !unicode.IsLetter(first) {
135+
return false
136+
}
137+
rest := s[size:]
138+
if rest == "" {
139+
return false
140+
}
141+
142+
return skipRunes(rest, 0, isNameRune) == len(rest)
143+
}
144+
145+
// annotationArgument reads the raw, unvalidated argument of a marker on line.
146+
//
147+
// The shape is: the marker starting the line, AT LEAST ONE space separator, then a non-empty
148+
// argument that does not itself begin with a whitespace character, with trailing space separators
149+
// dropped. The argument's content is not inspected — `swagger:parameters` hands it to the grammar,
150+
// which diagnoses a malformed one rather than skipping it here, and the malformed-name detectors
151+
// compare it against what overrideName accepts.
152+
//
153+
// One case reads differently from the expression this replaced, deliberately: that pattern could
154+
// start the argument ON a space separator. Its `\S` excludes the ASCII whitespace characters and
155+
// nothing else, so a non-breaking space passed it, and when what followed the separator run was a
156+
// tab (or nothing at all) the pattern gave a separator back and began the argument there. The
157+
// argument here begins where the separators end, or there is none. Nothing an author would write
158+
// reaches the difference.
159+
func annotationArgument(line, keyword string) (string, bool) {
160+
tail, ok := annotationTail(line, keyword)
161+
if !ok {
162+
return "", false
163+
}
164+
165+
arg := strings.TrimLeftFunc(tail, isSpaceSeparator)
166+
if len(arg) == len(tail) {
167+
return "", false // no separator between the marker and its argument
168+
}
169+
170+
arg = strings.TrimRightFunc(arg, isSpaceSeparator)
171+
if arg == "" {
172+
return "", false
173+
}
174+
if first, _ := utf8.DecodeRuneInString(arg); isASCIISpace(first) {
175+
return "", false
176+
}
177+
178+
return arg, true
179+
}
180+
181+
// annotationName returns the keyword of the first `swagger:<name>` marker on line.
182+
//
183+
// Deliberately loose — this is the classification search, not a gate: the marker may sit anywhere
184+
// on the line provided it follows start-of-line, whitespace or a `/`. Do NOT use it as a block
185+
// terminator; it fires on mid-prose mentions and would truncate descriptions.
186+
func annotationName(line string) (string, bool) {
187+
for from := 0; from < len(line); {
188+
at := strings.Index(line[from:], annotationKeyword)
189+
if at < 0 {
190+
return "", false
191+
}
192+
at += from
193+
194+
if at == 0 || isLooseBoundary(line[at-1]) {
195+
tail := line[at+len(annotationKeyword):]
196+
if end := skipRunes(tail, 0, isNameRune); end > 0 {
197+
return tail[:end], true
198+
}
199+
}
200+
from = at + 1
201+
}
202+
203+
return "", false
204+
}
205+
206+
// isLooseBoundary reports whether b may precede the keyword in the classification search.
207+
//
208+
// Byte-wise rather than rune-wise on purpose: every character it admits is ASCII, and a UTF-8
209+
// continuation byte can never be one of them.
210+
func isLooseBoundary(b byte) bool {
211+
switch b {
212+
case '\t', '\n', '\f', '\r', ' ', '/':
213+
return true
214+
default:
215+
return false
216+
}
217+
}

0 commit comments

Comments
 (0)
⌂ 换网址