fix: warn when <pre> tags lack <code> children in XML content

[fangshuyu-768]

Summary

Fixes two issues discovered during real-world usage of lark-cli for document generation:

1. <pre> tags without <code> children are silently dropped (HIGH)

The Lark Docs API silently discards <pre> blocks that don't contain <code> child elements. This PR adds client-side validation that emits a warning to stderr when this pattern is detected in XML content for both docs +create and docs +update.

Before: <pre lang="text">content</pre> → content silently lost, no warning
After: <pre lang="text">content</pre> → stderr warning: "

 block #1 is missing a  child element..."

2. block_insert_after response doesn't hint how to discover new block IDs (MEDIUM)
After a successful block_insert_after / block_copy_insert_after / append operation, the response now includes a _hint field suggesting the user fetch the document to discover newly created block IDs.
Changes



File
Change




shortcuts/doc/xml_validate.go
New: validatePreTags() + emitPreWarnings()


shortcuts/doc/xml_validate_test.go
New: 11 test cases for pre tag validation


shortcuts/doc/docs_create_v2.go
validateCreateV2: emit pre warnings when --doc-format xml


shortcuts/doc/docs_update_v2.go
validateUpdateV2: emit pre warnings; executeUpdateV2: inject _hint


shortcuts/doc/docs_create_test.go
2 new tests: pre warning / no false positive


shortcuts/doc/docs_update_test.go
3 new tests: pre warning / block_insert_after hint / append hint



Verification

make unit-test — all 80+ packages pass
go vet ./... — clean
gofmt -l — no output


Summary by CodeRabbit

New Features

Added validation warnings when creating or updating XML-formatted documents with <pre> blocks missing <code> child elements.
Added response hints for document update operations that guide users to refetch documents to discover newly inserted block IDs.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds XML validation and user guidance to document operations. A new validation module detects <pre> blocks missing <code> children and emits warnings. The validation integrates into both create and update flows, and response hints instruct users to refetch documents after block insertion operations.

Changes

XML Pre-Tag Validation and Integration

Layer / File(s)	Summary
XML validation foundation shortcuts/doc/xml_validate.go, shortcuts/doc/xml_validate_test.go	New regex-based validation finds <pre> blocks and warns when <code> children are missing; unit tests cover edge cases including missing tags, self-closing blocks, multiline structures, and attribute-only occurrences.
Create V2 validation integration shortcuts/doc/docs_create_v2.go, shortcuts/doc/docs_create_test.go	Create-v2 flow validates XML content and emits warnings; tests assert warnings appear for malformed <pre> blocks and are absent when <pre> contains <code>.
Update V2 validation and hints shortcuts/doc/docs_update_test.go, shortcuts/doc/docs_update_v2.go	Update-v2 flow validates XML content and emits warnings; response hints inject _hint field for block insertion and append operations, instructing users to run docs +fetch to discover newly created block IDs. Integration tests validate warning emission and hint presence.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

Possibly related PRs

• larksuite/cli#1291: Both PRs enhance the create-v2 validation flow; PR #1291 adds validateDocsV2Only pre-validation while this PR adds XML <pre>/<code> validation warnings.

Suggested labels

size/M, domain/ccm

Suggested reviewers

• SunPeiYang996
• liangshuo-1

Poem

🐰 The pre-tags now dance with code in sight,
Warnings whisper when structure's not quite right,
Hints guide users to refetch anew,
XML validation—shiny and true!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically summarizes the main change: adding warnings for pre tags missing code children in XML content, which directly matches the PR's primary objective.
Description check	✅ Passed	The description comprehensively covers all required template sections with detailed summaries, specific changes, verification steps, and related issues, providing excellent context for reviewers.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/doc-pre-code-validation

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 71.61%. Comparing base (03ea6e7) to head (3c24f2e).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1344      +/-   ##
==========================================
+ Coverage   71.58%   71.61%   +0.03%     
==========================================
  Files         689      690       +1     
  Lines       65521    65552      +31     
==========================================
+ Hits        46901    46946      +45     
+ Misses      14972    14955      -17     
- Partials     3648     3651       +3     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

🚀 PR Preview Install Guide

🧰 CLI update

npm i -g https://pkg.pr.new/larksuite/cli/@larksuite/cli@3c24f2ef768995f22cc2924d7e91f21d3f688463

🧩 Skill update

npx skills add larksuite/cli#fix/doc-pre-code-validation -y -g

[coderabbitai]

🧹 Nitpick comments (1)

shortcuts/doc/docs_update_v2.go (1)

110-115: 💤 Low value

Minor redundancy in content check (acceptable).

The content != "" check on line 111 is redundant since validatePreTags already returns nil for empty content (xml_validate.go:22-24). However, this is harmless defensive coding that avoids an unnecessary function call. Note that docs_create_v2.go:36 doesn't include this check, creating a slight inconsistency, but both approaches work correctly.

🤖 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_v2.go` around lines 110 - 115, The code redundantly
checks content != "" before calling validatePreTags (which already returns nil
for empty content); to remove this minor inconsistency, drop the content != ""
condition so the block only checks runtime.Str("doc-format") == "xml" &&
runtime.Factory != nil and then calls validatePreTags(content) and
emitPreWarnings(...) when warnings are returned; update the surrounding if to
mirror docs_create_v2.go behavior and keep validatePreTags, emitPreWarnings and
the runtime checks intact.

🤖 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_v2.go`:
- Around line 110-115: The code redundantly checks content != "" before calling
validatePreTags (which already returns nil for empty content); to remove this
minor inconsistency, drop the content != "" condition so the block only checks
runtime.Str("doc-format") == "xml" && runtime.Factory != nil and then calls
validatePreTags(content) and emitPreWarnings(...) when warnings are returned;
update the surrounding if to mirror docs_create_v2.go behavior and keep
validatePreTags, emitPreWarnings and the runtime checks intact.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 1b9516cf-c63b-4582-b809-87d6ded8e0e0

📥 Commits

Reviewing files that changed from the base of the PR and between 03ea6e7 and 3c24f2e.

📒 Files selected for processing (6)

• shortcuts/doc/docs_create_test.go
• shortcuts/doc/docs_create_v2.go
• shortcuts/doc/docs_update_test.go
• shortcuts/doc/docs_update_v2.go
• shortcuts/doc/xml_validate.go
• shortcuts/doc/xml_validate_test.go

[fangshuyu-768]

Closing: the

 validation should be fixed server-side in the docs_ai API rather than with client-side regex. Will re-submit with only the _hint UX improvement.