Skip to content

fix(api): locate docs diagnostics, report all broken pages, accept markdown articles - #208

Merged
s3rot0n1n merged 3 commits into
mainfrom
fix/docs-diagnostics-and-article-markdown
Nov 17, 2026
Merged

s3rot0n1n merged 3 commits into
mainfrom
fix/docs-diagnostics-and-article-markdown

Conversation

@s3rot0n1n

Copy link
Copy Markdown
Contributor

Three fixes found while porting a real docs site to FrontLit and saving an article over MCP.

Changes

  • text-editor: locate schema failures. requireDocsContent failures (for example a bullet that starts with 1.) used to carry only a fieldPath, so the Git check produced no annotation. The Markdown parser now maps each top-level node back to its source block, and these errors carry file, line and column. Patch changeset for @frontlit/text-editor.
  • api: report every broken docs page at once. The documentation importer collects per-file content errors, SECTION_COLLISION and DUPLICATE_ROUTE problems and throws once, instead of stopping at the first page. New gitCheckAnnotations / gitCheckCodes helpers (used by the check worker and publication checks): diagnostics without a line are annotated at line 1 instead of dropped, annotations are capped at 50 with a summary saying how many were found.
  • api: Markdown bodies for articles and product updates. Create and update accept markdown as an alternative to content over REST and MCP; it's parsed with the docs parser (frontmatter: false), and invalid Markdown returns 422 diagnostics with line numbers. Sending both is INVALID_REQUEST. Create now also stores content when given. Contract schemas, 400/422 responses and MCP descriptions updated.

Testing

  • @frontlit/text-editor: 115 tests pass; typechecks pass.
  • API documentation, documents and MCP suites: 398 passed. Each full run had one failure, a different test each time (deletion-ledger, migration-prs, source.test.ts), and each passed alone. Not yet compared with main.
  • New tests: content.test.ts (locations), markdown-body.test.ts, a schema check in rendering.test.ts.

After merging

The skill's local checker shows the new line numbers once @frontlit/text-editor is released; the API changes need a deploy.

🤖 Generated with Claude Code

Rajat and others added 3 commits November 17, 2026 09:26
Diagnostics raised by the post-conversion schema check now carry the
file plus the line and column of the top-level Markdown block that
produced the offending node, so the docs validation check can annotate
them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The Git importer now keeps going through all Markdown files, collects
each page's diagnostics (parse, slug, section collision, duplicate
route) and throws them together; tree-level problems still fail fast.
Check annotations are built in one place: a diagnostic with a file but
no line is annotated at line 1, and annotations are capped at 50 with
the remaining count noted in the summary.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Create and update for articles and product updates take an optional
markdown string on REST and MCP, converted with the documentation
parser. It is exclusive with content, and create now stores the body
it is given instead of always starting empty. Conversion failures come
back as the documentation validation error body (400/422) rather than
a server error. A text-editor test pins that docs Markdown output is
valid, unchanged, in the article editor schema and renders.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-17T05:25:00.660750Z 95485a1 PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 95485a1ae3

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

const parsed = parseDocsMarkdown(markdown, { file: entry.path });
let parsed: ReturnType<typeof parseDocsMarkdown>;
let resolved: ReturnType<typeof resolveDocsSourcePath>;
try {

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Collect per-file decoding errors

When a Markdown blob contains invalid UTF-8 or a NUL byte and appears before other broken pages, read(entry) throws before this try block, so the importer still stops at the first page and omits diagnostics for later pages. Collect these per-file read errors while keeping repository-wide size-limit failures fatal so the check can report all broken pages.

Useful? React with 👍 / 👎.

@s3rot0n1n
s3rot0n1n merged commit 6281390 into main Nov 17, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant