Skip to content

test(library): read the public-surface Name tables through mdast instead of a hand parser - #569

Merged
Vivswan merged 1 commit into
mainfrom
refactor/public-surface-mdast
Oct 27, 2026
Merged

Vivswan merged 1 commit into
mainfrom
refactor/public-surface-mdast

Conversation

@Vivswan

@Vivswan Vivswan commented Oct 26, 2026

Copy link
Copy Markdown
Owner

What this changes

documentedNames: quote-depth stripping, a fence tracker, header/row/delimiter regexes, a blank-line table loop
  ->  mdast-util-from-markdown + gfmTable, visitParents over each API-section block for its table nodes;
      a Name table is a header whose first cell is `Name`, each body row's first cell one code span

differential, old against new:
  the real library page                  132 names   same
  the 16 variants the controls build     same answer each
  4000 generated pages, 35 block forms   1674 differ, on 8 forms, each GitHub's rendering

How

  • The eight forms where the hand parser and GitHub disagreed: a space inside a code span is a name; \| in a code span unescapes; a heading, quote, or list item glued to table rows ends the table; a four-space-indented table is code; a table inside an HTML block is raw HTML; a quoted or indented ## is content, not the section end. No real page carries one.
  • Library: the mdast GFM table stack already in the repository; unist-util-visit-parents 6.0.2 becomes a direct devDependency, the identical line refactor(scripts): walk the markdown tree with unist-util-visit-parents in generated-regions #562 adds.

Proof

  • Tests: public-surface 23 pass, four new negative controls for the forms above, each red against the old scan.
  • Gates: typecheck, fleet biome 0, member-shape 0, knip, line cap.
Technical details

documentedNames pinned the `| Name |` tables of docs/reference/library.md to the names src/index.ts exports with a hand parser: a quote-depth stripper, a fence tracker per quote depth, three regexes for the Name header, the delimiter row, and a code-span first cell, and a line loop that opened a table on header plus delimiter and closed it on a blank line. It now parses the page with mdast-util-from-markdown and the GFM table extensions (micromark-extension-gfm-table, mdast-util-gfm-table), the stack .github/scripts/lib/generated-regions.ts already uses, and reads the tree: the root blocks between `## The API by group` and the next second-level heading, every table under them visited through unist-util-visit-parents, added as a direct devDependency for it; a Name table is one whose header's first cell is the text `Name`; a body row's first cell must be one code span, else the row is refused with its line and source as before. Deleted: QuotedLine, quotedLine, outsideFences, opensNameTable, isNameTableDelimiter, and the three regexes.

Differential, old scan against new: the real page gives the same 132 names; the 16 page variants the existing negative controls build give the same answer each (the same names, or the same refusal). Over 4000 generated pages composed from 35 block forms, 1674 differ, on 8 forms, and in each the new answer is how GitHub renders the page: a code span with a space is read as a name (the equality then reports it); an escaped pipe inside a code span is unescaped; a heading, a blockquote line, or a list item directly after a table's rows ends the table, where the old scan refused it as a malformed row; a four-space-indented table is an indented code block; a markdown table inside an HTML block is raw HTML; and a quoted or indented `## ` line is content, not the section's end, so a bad row behind one is now reached and refused. Four of those forms became negative controls, each seen red against the old scan: the indented and HTML-block tables hold shown text, a table whose rows run into a heading still documents its names, and a table after a quoted second-level heading does too.
Copilot AI balanced review requested due to automatic review settings October 26, 2026 21:12
@github-actions

Copy link
Copy Markdown
Contributor

File size check

0 over a hard cap (fails), 6 warning(s).

File Size Tier Cap
src/engine/diff.ts:56 11 comment lines warn 10
src/github/api-error.ts:9 11 comment lines warn 10
src/problem.ts:73 18 comment lines warn 10
src/sections/contract/errors.ts:13 11 comment lines warn 10
src/sections/contract/module.ts:55 12 comment lines warn 10
src/sections/shared/list/decl.ts:265 14 comment lines warn 10

Split the file, wrap the line, shorten or exempt the comment, or list the path in .file-size-allow.local with a # reason.

5 managed file(s) skipped; repo-platform owns them.

Copilot AI 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.

🟢 Approval recommended

The scoped test-only refactor and matching dependency updates have no identified blocking defects.

No open issues 🎉

What changed in this PR

Replaces the public-surface test's hand-written Markdown parser with an mdast GFM table parser, aligning documented API name checks with GitHub's rendering.

Changes:

  • Extracts names from parsed tables within the API section, preserving row validation and duplicate detection.
  • Adds regression controls for indented code, HTML blocks, table-ending headings, and quoted headings.
  • Adds unist-util-visit-parents as a direct development dependency.
File Description
test/​library/​public-surface.test.ts Migrates table extraction to mdast and adds regression controls.
package.json Declares the tree traversal dependency.
bun.lock Records the matching direct dependency.

Review effort: Balanced

@Vivswan
Vivswan marked this pull request as ready for review October 26, 2026 21:16
@Vivswan
Vivswan merged commit 2ee3f11 into main Oct 27, 2026
31 checks passed
@Vivswan
Vivswan deleted the refactor/public-surface-mdast branch October 27, 2026 07:18
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.

2 participants