feat(doc): add v2 XML content guards for bare ampersands and deprecated tags - #822
feat(doc): add v2 XML content guards for bare ampersands and deprecated tags#822herbertliu wants to merge 5 commits into
Conversation
…ed tags Add pre-flight checks for the v2 XML document path: - CheckV2XMLBareAmpersand: returns a hard error when content contains a bare & that is not a valid XML entity reference (&, <, >, ', ", &#N;, &#xH;). Such bare ampersands cause the v2 XML parser to reject the request. - CheckV2XMLWarnings: returns non-fatal warnings for two silently-wrong constructs — <quote-container> (v2 drops it; use <blockquote>) and <column width="N"> with an integer value (has no effect; use width-ratio="0.N"). Both checks are integrated into validateCreateV2/validateUpdateV2 (hard error) and executeCreateV2/executeUpdateV2 (warnings to stderr). Only fires when --doc-format is xml (the default).
github-actions
Bot
added
domain/ccm
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughAdds v2 XML validators: a fatal bare-ampersand check and non-fatal warnings for unsupported constructs; wires validators into create/update v2 CLI validate/execute paths; adds unit tests and E2E dry-run tests covering failure and warning behaviors. ChangesXML V2 Validation and Warning System
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Suggested labels
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@shortcuts/doc/docs_update_check.go`:
- Around line 313-317: The current regex columnIntWidthRe is too permissive and
misses valid forms; change it to require a preceding whitespace before the
attribute, allow optional spaces around '=', accept single or double quotes, and
capture the integer value (e.g. `<column\b[^>]*\swidth\s*=\s*(['"])(\d+)\1`) so
it won't match attributes like data-width and will match forms like width='50'
or width = "50". Apply the same tightening to the other related regex defined
around lines 335-341 so both matchers use `\swidth\s*=\s*(['"])(\d+)\1` (or the
float equivalent) and keep the surrounding `<column\b[^>]*` context to limit
matches to column elements.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: bc2981b2-3f9c-4a87-909d-8b36a95bd73c
📒 Files selected for processing (4)
shortcuts/doc/docs_create_v2.goshortcuts/doc/docs_update_check.goshortcuts/doc/docs_update_check_test.goshortcuts/doc/docs_update_v2.go
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## main #822 +/- ##
==========================================
+ Coverage 65.67% 65.93% +0.25%
==========================================
Files 513 523 +10
Lines 47655 49737 +2082
==========================================
+ Hits 31297 32793 +1496
- Misses 13652 14142 +490
- Partials 2706 2802 +96 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
🚀 PR Preview Install Guide🧰 CLI updatenpm i -g https://pkg.pr.new/larksuite/cli/@larksuite/cli@f50175243be99ce47169f42837a81af6919ed9b2🧩 Skill updatenpx skills add larksuite/cli#feat/docs-v2-xml-content-guard -y -g |
There was a problem hiding this comment.
🧹 Nitpick comments (1)
shortcuts/doc/docs_update_check_test.go (1)
474-497: ⚡ Quick winUse
strings.Containsinstead of custom substring scanner.The
containsStrfunction at line 487 is locally scoped to this test file, used only once at line 479, and thestringspackage is already imported. Replace it withstrings.Containsto eliminate the unnecessary custom implementation.Proposed simplification
@@ for _, sub := range tt.wantContains { - if !containsStr(combined, sub) { + if !strings.Contains(combined, sub) { t.Errorf("expected warning to contain %q, got: %s", sub, combined) } } }) } } - -func containsStr(s, sub string) bool { - return len(s) >= len(sub) && (s == sub || len(sub) == 0 || - func() bool { - for i := 0; i+len(sub) <= len(s); i++ { - if s[i:i+len(sub)] == sub { - return true - } - } - return false - }()) -}🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@shortcuts/doc/docs_update_check_test.go` around lines 474 - 497, The test defines a local containsStr function and calls it to check substrings; replace that call with the standard strings.Contains and remove the custom containsStr function to simplify the test (ensure the strings package is imported and used in the assertion where containsStr was invoked, and delete the containsStr function declaration to avoid redundancy).
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@shortcuts/doc/docs_update_check_test.go`:
- Around line 474-497: The test defines a local containsStr function and calls
it to check substrings; replace that call with the standard strings.Contains and
remove the custom containsStr function to simplify the test (ensure the strings
package is imported and used in the assertion where containsStr was invoked, and
delete the containsStr function declaration to avoid redundancy).
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: ae956902-4be3-4375-a43b-58e4b2cd6efa
📒 Files selected for processing (2)
shortcuts/doc/docs_update_check.goshortcuts/doc/docs_update_check_test.go
🚧 Files skipped from review as they are similar to previous changes (1)
- shortcuts/doc/docs_update_check.go
fangshuyu-768
left a comment
fangshuyu-768
left a comment
There was a problem hiding this comment.
Thanks for adding these pre-flight checks — the overall approach of catching silent failures early is solid. I have a few concerns below, ordered by impact.
… containsStr helper, align empty-content guard
…E tests - Replace columnIntWidthRe with columnWidthAttrRe + isIntWidth to reject mixed-quote matches since Go RE2 lacks backreferences; capture opening/closing quotes and verify they match - Remove redundant content != empty guards in validate paths since CheckV2XMLBareAmpersand returns empty safely - Add TestIsIntWidth unit test and mixed-quote test case - Add dry-run E2E tests for v2 create/update XML guard paths
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@tests/cli_e2e/docs/docs_update_dryrun_test.go`:
- Around line 77-83: Add isolated config directories for the new E2E tests by
setting LARKSUITE_CLI_CONFIG_DIR to t.TempDir() where the other environment vars
are set (next to t.Setenv("LARKSUITE_CLI_APP_ID", ...),
t.Setenv("LARKSUITE_CLI_APP_SECRET", ...) and t.Setenv("LARKSUITE_CLI_BRAND",
...)) in both new tests (the block shown and the second block around the 125-130
area) so each test uses its own config directory.
- Around line 152-170: In the subtest "warning-only content passes dry-run" add
assertions that the dry-run request envelope in the CLI output matches the
expected update shape (action/update, doc "doxcnDryRunE2E", command "overwrite",
content includes the quote-container HTML, and dryRun true) similar to the
create-test pattern; parse the CLI output (from result.Stdout or combined
output) to extract the request JSON and assert those fields on the request
object returned by clie2e.RunCmd without invoking any real APIs.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: aed3c6b6-2baf-49bc-8260-e7679bdfd9fb
📒 Files selected for processing (5)
shortcuts/doc/docs_create_v2.goshortcuts/doc/docs_update_check.goshortcuts/doc/docs_update_check_test.goshortcuts/doc/docs_update_v2.gotests/cli_e2e/docs/docs_update_dryrun_test.go
🚧 Files skipped from review as they are similar to previous changes (2)
- shortcuts/doc/docs_create_v2.go
- shortcuts/doc/docs_update_v2.go
…tion and envelope assertions in E2E tests - isIntWidth now returns false for empty string instead of true - Add LARKSUITE_CLI_CONFIG_DIR isolation in v2 create/update E2E tests - Add gjson assertions for API method/URL in update dry-run success path
There was a problem hiding this comment.
🧹 Nitpick comments (1)
shortcuts/doc/docs_update_check.go (1)
326-336: ⚡ Quick winConsider using
strconv.Atoifor clearer integer validation.The current implementation only checks for absence of a decimal point, relying on the regex pre-filtering the input to
[0-9.]+. While this works correctly in context, usingstrconv.Atoiwould be more idiomatic Go, eliminate the hidden coupling to the regex, and make the function reusable.♻️ More idiomatic implementation
func isIntWidth(s string) bool { - if s == "" { - return false - } - for _, c := range s { - if c == '.' { - return false - } - } - return true + _, err := strconv.Atoi(s) + return err == nil }Don't forget to add
"strconv"to the imports at the top of the file.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@shortcuts/doc/docs_update_check.go` around lines 326 - 336, Replace the manual dot-check in isIntWidth with an attempt to parse the string as an integer using strconv.Atoi: in isIntWidth(s string) call strconv.Atoi(s) and return true only when it succeeds (err == nil); also import "strconv" at the top of the file so the function no longer relies on external regex assumptions and becomes a proper integer validator.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@shortcuts/doc/docs_update_check.go`:
- Around line 326-336: Replace the manual dot-check in isIntWidth with an
attempt to parse the string as an integer using strconv.Atoi: in isIntWidth(s
string) call strconv.Atoi(s) and return true only when it succeeds (err == nil);
also import "strconv" at the top of the file so the function no longer relies on
external regex assumptions and becomes a proper integer validator.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 0795fb4f-44ff-4e6a-b61c-ac08ab42608d
📒 Files selected for processing (3)
shortcuts/doc/docs_update_check.goshortcuts/doc/docs_update_check_test.gotests/cli_e2e/docs/docs_update_dryrun_test.go
🚧 Files skipped from review as they are similar to previous changes (2)
- shortcuts/doc/docs_update_check_test.go
- tests/cli_e2e/docs/docs_update_dryrun_test.go
|
Thanks for looking into this and for the thoughtful guardrails here. For the unescaped ampersand case, for example For I am going to close this PR for now. If you have a better idea or want to discuss another approach, I would be happy to continue the conversation. |
3 participants
Summary
Add pre-flight static checks for the v2 XML document path to catch two categories of silent failures before the API call is made.
Changes
shortcuts/doc/docs_update_check.go: AddCheckV2XMLBareAmpersand(hard error) andCheckV2XMLWarnings(non-fatal warnings) with table-driven testsshortcuts/doc/docs_create_v2.go: Integrate bare-ampersand check invalidateCreateV2and XML warnings inexecuteCreateV2shortcuts/doc/docs_update_v2.go: Same integration invalidateUpdateV2/executeUpdateV2shortcuts/doc/docs_update_check_test.go: AddTestCheckV2XMLBareAmpersandandTestCheckV2XMLWarningsChecks
CheckV2XMLBareAmpersand— hard error (returned from Validate):&that is not a recognised XML entity (&,<,>,',",&#N;,&#xH;).CheckV2XMLWarnings— non-fatal warnings (printed to stderr before the API call):<quote-container>— v2 silently drops the block; the correct tag is<blockquote>.<column width="N">with an integer value — has no effect in v2; the correct attribute iswidth-ratio="0.5"(float 0–1).Both checks only fire when
--doc-formatisxml(the default).Test Plan
go test ./shortcuts/doc/...— all pass, 66.4% coveragego vet ./...— cleangofmt -l .— cleanSummary by CodeRabbit
New Features
Tests