fix: resolve more intra-repo doc links and add tests#16
Merged
Conversation
Address PR review on gravity-ui/uikit#2740: - rewriteDocLinks now handles any repo-relative link, not just README.md targets: bare-folder links (../Portal) resolve to the sibling doc, and links to non-shipped files (../types.ts, unshipped legacy/) are unwrapped to plain text — keeping the "no dead link remains" promise. External URLs and in-page anchors are left untouched. - Skip a README sitting directly at a baseDir (empty name → blank index entry). - Add node:test coverage for cleanMarkdown/extractSummary/extractTitle and an integration test for buildDocs link rewriting, and run it in CI. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
buildDocs now lifts the package README's `For AI agents` section (cleaned) to the top of the generated INDEX.md, and appends a `Documentation for AI agents` pointer section to that README (idempotently) linking to the generated tree. Adds `extractSection` helper and tests for both behaviors. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Replace the hand-rolled README parsing used to form INDEX.md with @gravity-ui/readme-validator, which parses on a real Markdown AST: - component title/summary via parseComponentReadme - package overview (For AI agents positioning + prose, Install, Usage) via parsePackageReadme Drop the now-unused extractSummary/extractTitle (and their exports); keep cleanMarkdown/extractSection for doc-body cleanup and pointer idempotency. Add an ambient d.ts since the package ships no types, and pin engines.node >=20.19 (readme-validator is ESM-only; CJS consumers require() it). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1.2.3 ships a real CommonJS entry (plus matching types), so the CJS build of gulp-utils can require() it — 1.2.2 was ESM-only and broke CommonJS consumers (uikit's gulpfile). Drop the local ambient d.ts now that the package bundles its own type declarations. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
korvin89
approved these changes
Jul 15, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Follow-up to #14, addressing review feedback on gravity-ui/uikit#2740.
Link rewriting (
rewriteDocLinks)Previously only links whose target contained
README.mdwere rewritten; everything else shipped unchanged, which left dead links in the docs and contradicted the "no dead link remains" docstring. Now any repo-relative link is handled:[Portal](../Portal)resolves to the sibling doc./Portal.md(READMEs are now keyed by their folder as well as their file path). Verified on uikit:../Portal,../Icon,../Buttonall resolve; zero dead../Namelinks remain.[actions](./types.ts#L9), unshippedlegacy/, etc. are unwrapped to plain text (link text kept).#section) are left untouched.Other
README.mdsitting directly at abaseDirwas silently emittingcomponents/.md; such items are now skipped.node:testcoverage (run in CI) —cleanMarkdowndrops SANDBOX/LANDING, keeps GITHUB_BLOCK content, strips badges;extractSummaryskips the import fence / is empty when a heading follows the title / unwraps links;buildDocslink rewriting (README-path, bare-folder, unwrap, external, legacy exclusion, index) against a small fixture package.tsxas a dev dependency and ateststep to CI.Not changed: reference-style link syntax and the
extractSummaryheuristic (Sourcery's notes) — the summary convention is intentional (empty when a README doesn't follow it), and no docs use reference-style links today; can revisit if that changes.🤖 Generated with Claude Code