Skip to content

Commit 5b9e9bc

Browse files
committed
fix: exclude cross-library re-exports from API docs output
TypeDoc merges all .d.ts files into one documentation set, causing the shared 'sap' namespace to duplicate content across library directories. For example, sap.f/namespaces/sap/namespaces/m/ contained sap.m classes, and sap.f/sap/tnt/ contained sap.tnt enums (from a module augmentation). The fix collects which modules each .d.ts file declares, then excludes pages that either: - Don't match any declared module (namespace re-export artefacts) - Match a module whose namespace belongs to another library (augmentation) This removes ~54 duplicate pages per library that had cross-library content, reducing confusion and improving the signal-to-noise ratio for crawlers.
1 parent c29ced6 commit 5b9e9bc

2 files changed

Lines changed: 58 additions & 2 deletions

File tree

‎scripts/generate-api-docs/generate-index-pages.mjs‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@
1717
*/
1818

1919
import { readdirSync, readFileSync, writeFileSync, existsSync, statSync } from "fs";
20-
import { join, basename } from "path";
20+
import { join } from "path";
2121

2222
// --- Argument parsing ---
2323

@@ -226,7 +226,9 @@ if (latestOpenUI5) {
226226
}
227227
}
228228

229-
llmsTxt += `\n## Resources\n
229+
llmsTxt += `
230+
## Resources
231+
230232
- [Sitemap Index](${SITE_URL}/sitemap.xml): Machine-readable index of all per-version sitemaps
231233
- [UI5 & TypeScript Guide](${SITE_URL}/): Getting started, FAQ, release notes
232234
- [npm: @openui5/types](https://www.npmjs.com/package/@openui5/types): OpenUI5 type definitions package

‎scripts/generate-api-docs/generate.mjs‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -103,15 +103,26 @@ let totalReplacements = 0;
103103
// Maps module path → default export name, e.g. "sap/m/Button" → "Button", "sap/ui/core/Element" → "UI5Element"
104104
const defaultExports = new Map();
105105

106+
// Also collect which module paths are declared in each library file.
107+
// This is used later to exclude cross-library re-exports from the output.
108+
// Maps library name (e.g. "sap.f") → Set of module paths declared in that .d.ts
109+
const libraryModules = new Map();
110+
106111
for (const file of dtsFiles) {
107112
const filePath = join(TYPES_DIR, file);
108113
const content = readFileSync(filePath, "utf8");
109114

115+
// Track which modules are declared in this library file (e.g. "sap.f.d.ts" → "sap.f")
116+
const libName = file.replace(/\.d\.ts$/, ""); // e.g. "sap.f"
117+
if (!libraryModules.has(libName)) libraryModules.set(libName, new Set());
118+
const libModules = libraryModules.get(libName);
119+
110120
// Find: declare module "sap/m/Button" { ... export default class Button
111121
const moduleRegex = /^declare module "([^"]+)"/gm;
112122
let moduleMatch;
113123
while ((moduleMatch = moduleRegex.exec(content)) !== null) {
114124
const moduleName = moduleMatch[1];
125+
libModules.add(moduleName);
115126
const moduleStart = moduleMatch.index;
116127
// Find the next declare module to bound our search
117128
const nextModule = content.indexOf("\ndeclare module ", moduleStart + 1);
@@ -365,11 +376,54 @@ let skippedCount = 0;
365376
// Directories/files to exclude from output (not UI5-specific)
366377
const EXCLUDE_PATTERNS = ["interfaces/JQuery", "interfaces/JQuery.", "/JQueryStatic", "JQueryPromise"];
367378

379+
// Precompute namespace prefixes for all libraries (used to detect augmentations)
380+
// e.g. "sap.f" → "sap/f/", "sap.ui.core" → "sap/ui/core/"
381+
const libNamespacePrefixes = new Map();
382+
for (const lib of libraryModules.keys()) {
383+
libNamespacePrefixes.set(lib, lib.replace(/\./g, "/") + "/");
384+
}
385+
368386
function shouldExclude(relPath) {
369387
// Exclude jQuery-related pages
370388
if (EXCLUDE_PATTERNS.some((p) => relPath.includes(p))) return true;
371389
// Exclude residual "default.html" pages (from un-renamed default exports)
372390
if (relPath.endsWith("/default.html")) return true;
391+
// Exclude cross-library re-exports.
392+
// TypeDoc merges all .d.ts files into one documentation set, so the shared "sap" namespace
393+
// causes content from other libraries to appear under each library's directory.
394+
// We exclude a page if:
395+
// (a) it doesn't match any module declared in the library's own .d.ts, OR
396+
// (b) the module it matches belongs to another library's namespace (an augmentation).
397+
// For example, sap.f.d.ts augments "sap/tnt/library" — but sap.tnt owns that namespace,
398+
// so we exclude it from sap.f's output. Meanwhile sap.ui.core.d.ts declares "sap/base/Log"
399+
// which no other library owns, so it stays.
400+
const libMatch = relPath.match(/^(sap\.[^/]+)\//);
401+
if (libMatch) {
402+
const lib = libMatch[1]; // e.g. "sap.f"
403+
const afterLib = relPath.slice(lib.length + 1); // path after "sap.f/"
404+
// Always keep the library's own README (the module index page)
405+
if (afterLib === "README.html") return false;
406+
// Check against the definitive module list for this library
407+
const modules = libraryModules.get(lib);
408+
if (modules && modules.size > 0) {
409+
// Find the declared module that matches this page's path (iterate Set directly)
410+
let matchingModule;
411+
for (const mod of modules) {
412+
if (afterLib.startsWith(mod + "/")) {
413+
matchingModule = mod;
414+
break;
415+
}
416+
}
417+
if (!matchingModule) return true; // no matching module → re-export/namespace artefact
418+
// Check if another library owns this module's namespace (= augmentation)
419+
const moduleNs = matchingModule + "/"; // e.g. "sap/tnt/library/"
420+
for (const [otherLib, otherNs] of libNamespacePrefixes) {
421+
if (otherLib !== lib && moduleNs.startsWith(otherNs)) {
422+
return true;
423+
}
424+
}
425+
}
426+
}
373427
return false;
374428
}
375429

0 commit comments

Comments
 (0)