html-parser

@advance-labs/html-parser

Pure, synchronous HTML extraction for the AEO Toolkit. Given an HTML string and the URL it came from, it produces the shared ParsedHtml shape: document meta, OpenGraph and Twitter cards, the heading tree, images with alt coverage, internal/external links, content-quality signals (word count, FAQ/HowTo, question headings, structure counts), and raw structured-data blocks. No network and no filesystem access — fetching is the job of @advance-labs/crawler, and full schema.org validation is the job of @advance-labs/schema-validator; this package only collects the raw blocks they need.

Usage

import { parseHtml } from '@advance-labs/html-parser';

const parsed = parseHtml(htmlString, 'https://example.com/page');

console.log(parsed.meta.title, parsed.meta.titleLength);
console.log(parsed.openGraph.complete);
console.log(parsed.imageAltCoverage); // 0..1
console.log(parsed.content.hasFaq, parsed.content.questionHeadingCount);
console.log(parsed.rawStructuredData); // [{ format: 'json-ld', data: {...} }, ...]

Each extractor is also exported standalone (accepting an HTML string), so a consumer can pull a single signal without parsing the whole document:

import { extractMeta, extractHeadings } from '@advance-labs/html-parser';

const meta = extractMeta(htmlString, url);
const headings = extractHeadings(htmlString);

Public API

Export	Signature	Purpose
parseHtml	(html: string, url: string) => ParsedHtml	Full extraction into the shared shape.
extractMeta	(html: string, url: string) => MetaTags	Title/description (+lengths), canonical, robots, viewport, charset, lang, theme-color.
extractOpenGraph	(html: string, url: string) => OpenGraph	OG tags; complete requires the og title/description/image/url quartet.
extractTwitter	(html: string, url: string) => TwitterCard	Twitter card tags (accepts name= and property=).
extractHeadings	(html: string) => HeadingNode[]	Heading tree h1–h6 in document order.
extractImages	(html: string, url: string) => ImageInfo[]	<img> with resolved src, hasAlt, dimensions.
extractLinks	(html: string, url: string) => LinkInfo[]	Anchors classified internal/external + nofollow.
computeContentSignals	(html: string) => ContentSignals	Word count, FAQ/HowTo, question headings, paragraph/list/table counts.
extractRawStructuredData	(html: string) => RawStructuredDataBlock[]	JSON-LD parsed; microdata/RDFa presence markers.
isHeadingHierarchyValid	(headings: HeadingNode[]) => boolean	True when headings never skip a level downward.
imageAltCoverage	(images: ImageInfo[]) => number	Fraction of images with alt text, 0..1.
internalLinkCount / externalLinkCount	(links: LinkInfo[]) => number	Link counts by classification.
isQuestionHeading	(text: string) => boolean	Whether a heading reads as a question.
jsonLdHasType / collectJsonLdTypes	see source	JSON-LD @type inspection helpers.

All shapes are imported from @advance-labs/types; this package never redefines them.

Notes

• hasFaq is set when an FAQ-flavored heading is present or an FAQPage/QAPage JSON-LD block exists. hasHowTo likewise combines headings and HowTo JSON-LD.
• An empty alt="" counts as not having descriptive alt text.
• Relative URLs in canonical, og:image, twitter:image, <img src>, and <a href> are resolved against the supplied page URL. Fragment-only (#...) anchors are skipped.
• Malformed JSON-LD is silently skipped (it surfaces as a validation finding downstream, not a parser crash).

Status

Implemented. All extractors are real (cheerio-backed) with no network/filesystem dependency and no stubs. Unit-tested with rich-page and sparse-page fixtures.