@tsdoctor/seo 0.1.0

package/StructuredData.js

@@ -0,0 +1,169 @@
+import { canonicalUrl } from "./Canonical.js";
+import { Result } from "effect";
+import { APIReference, JsonLdDocument, NodeRef, Person, SoftwareSourceCode, TechArticle } from "@effected/schema-org";
+
+//#region src/StructuredData.ts
+/**
+* The package node's `@id`.
+*
+* @remarks
+* A fragment on the package's own route rather than a bare URL, so the node
+* is distinguishable from the page that happens to sit at that route. Every
+* page in the API references this same id, which is what makes the package
+* node deduplicate across a crawl.
+*/
+const packageId = (input) => `${canonicalUrl(input.siteUrl, input.baseRoute)}#source`;
+/** An author or maintainer's `@id`, scoped to the package that credits them. */
+const personId = (input, name) => `${canonicalUrl(input.siteUrl, input.baseRoute)}#person-${encodeURIComponent(name)}`;
+/**
+* The people nodes a package credits, and refs to them.
+*
+* @remarks
+* The author is a `Person` when the manifest named a human and an
+* `Organization` when the name reads as a scope — but npm carries no such
+* distinction, so guessing would be fabrication. Everyone is a `Person`, which
+* is what the manifest field is documented to hold. An organization ends up
+* modelled as a person with an organization's name, which is imprecise rather
+* than wrong; inventing a type from a string's shape would be neither.
+*/
+function peopleNodes(input) {
+	const nodes = [];
+	const authors = [];
+	const seen = /* @__PURE__ */ new Set();
+	const add = (name, url) => {
+		const id = personId(input, name);
+		if (seen.has(id)) return;
+		seen.add(id);
+		nodes.push(Person.make({
+			"@id": id,
+			name,
+			...url !== void 0 ? { url } : {}
+		}));
+		authors.push(NodeRef.to(id));
+	};
+	if (input.attribution.authorName !== void 0) add(input.attribution.authorName, input.attribution.authorUrl);
+	for (const maintainer of input.attribution.maintainerNames) add(maintainer);
+	return {
+		nodes,
+		authors
+	};
+}
+/**
+* The `SoftwareSourceCode` node for a documented package, plus the people it
+* credits.
+*
+* @remarks
+* Note `version`, not `softwareVersion` — the latter reads like the right name
+* and is defined on `SoftwareApplication`, not here. It would serialize fine
+* and be silently ignored; the conformance validator is what catches it.
+*
+* `license` carries the canonical SPDX page for EVERY license the expression
+* names — schema.org's `license` accepts an array, and an `AND` expression has
+* no single answer to give. The URLs come from each catalog entry's own
+* `referenceUrl`, never from concatenating an id onto
+* `https://spdx.org/licenses/`: that is the string-building the catalog exists
+* to prevent, and it is wrong for a `LicenseRef`, which has no such page. A
+* license outside the catalog drops out of the array rather than appearing as
+* a fabricated URL.
+*
+* @param input - the per-API facts
+* @returns the reusable context every page in the API derives against
+*
+* @public
+*/
+function packageContext(input) {
+	const { nodes: people, authors } = peopleNodes(input);
+	const facts = input.attribution;
+	const pkg = SoftwareSourceCode.make({
+		"@id": packageId(input),
+		name: input.packageName,
+		url: canonicalUrl(input.siteUrl, input.baseRoute),
+		...input.description !== void 0 ? { description: input.description } : {},
+		...input.version !== void 0 ? { version: input.version } : {},
+		...facts.repositoryUrl !== void 0 ? { codeRepository: facts.repositoryUrl } : {},
+		programmingLanguage: ["TypeScript"],
+		...facts.licenseUrls.length > 0 ? { license: [...facts.licenseUrls] } : {},
+		...authors.length > 0 ? { author: [...authors] } : {},
+		...facts.keywords.length > 0 ? { keywords: [...facts.keywords] } : {},
+		...facts.homepage !== void 0 ? { sameAs: [facts.homepage] } : {}
+	});
+	return {
+		id: packageId(input),
+		nodes: [pkg, ...people],
+		siteUrl: input.siteUrl,
+		...input.version !== void 0 ? { version: input.version } : {}
+	};
+}
+/**
+* Derive the schema.org graph for one documentation page.
+*
+* @remarks
+* Three linked nodes plus the package's people: a `SoftwareSourceCode` for the
+* package, a `TechArticle` for the page, and an `APIReference` for the symbol
+* the page documents. The article `isPartOf` the package and its `mainEntity`
+* is the symbol, so a crawler reading any one node can reach the other two.
+*
+* Serialize the result with `JsonLdDocument.toScriptBody()`, never with
+* `JSON.stringify(graph.toJsonLd())` — `toScriptBody` is the only serializer
+* that escapes the sequences that would close the surrounding `<script>`
+* element, and it is idempotent, so an adapter layering its own escaping over
+* it is a no-op rather than a double-escape.
+*
+* @param pkg - the per-API context from {@link packageContext}
+* @param page - the per-page facts
+* @returns the assembled graph, or the identity failure that stopped it
+*
+* @public
+*/
+function derive(pkg, page) {
+	const pageUrl = canonicalUrl(pkg.siteUrl, page.pageRoute);
+	const articleId = `${pageUrl}#article`;
+	const symbolId = `${pageUrl}#symbol`;
+	const symbol = APIReference.make({
+		"@id": symbolId,
+		name: page.symbolName,
+		url: pageUrl,
+		description: page.description,
+		isPartOf: [NodeRef.to(pkg.id)],
+		...pkg.version !== void 0 ? { assemblyVersion: pkg.version } : {},
+		programmingModel: "TypeScript"
+	});
+	const article = TechArticle.make({
+		"@id": articleId,
+		name: page.symbolName,
+		headline: page.symbolName,
+		url: pageUrl,
+		description: page.description,
+		articleSection: [page.section],
+		datePublished: page.publishedTime,
+		dateModified: page.modifiedTime,
+		isPartOf: [NodeRef.to(pkg.id)],
+		mainEntity: NodeRef.to(symbolId),
+		inLanguage: "en"
+	});
+	return JsonLdDocument.buildResult([
+		...pkg.nodes,
+		article,
+		symbol
+	]);
+}
+/**
+* {@link derive}, serialized to the text an adapter embeds in a `<script>`.
+*
+* @remarks
+* The convenience the adapter actually wants: a page's structured data as a
+* string. Callers that need the graph itself — a conformance check in a test,
+* say — use {@link derive}.
+*
+* @param pkg - the per-API context from {@link packageContext}
+* @param page - the per-page facts
+* @returns the script body, or the identity failure
+*
+* @public
+*/
+function deriveScriptBody(pkg, page) {
+	return Result.map(derive(pkg, page), (graph) => graph.toScriptBody());
+}
+
+//#endregion
+export { derive, deriveScriptBody, packageContext };