@enhansome/core 1.11.0 → 1.12.0

package/dist/first-seen.js

@@ -9,7 +9,7 @@ export function firstSeenFor(previous, now) {
 }
 function collect(nodes, index) {
     for (const node of nodes) {
-        if (node.node_type === 'item' && node.first_seen) {
+        if (node.node_type === 'item' && node.repo_info && node.first_seen) {
             const existing = index.get(node.repo_info.id);
             if (existing === undefined || node.first_seen < existing) {
                 index.set(node.repo_info.id, node.first_seen);

package/dist/github.d.ts

@@ -86,6 +86,13 @@ export declare function getRepoInfo(octokit: GithubClient, owner: string, repo:
  */
 export declare function getRepoInfoOrNull(octokit: GithubClient, owner: string, repo: string): Promise<null | RepoInfoDetails>;
 export declare function getReadme(octokit: GithubClient, owner: string, repo: string, format?: 'html' | 'raw'): Promise<string>;
+/**
+ * One in-repo markdown file, for following a README's links into the source's
+ * content files. Returns null (logged) instead of failing the run: a followed
+ * file is best-effort the way repo-info failures are — only the README fetch
+ * itself can fail the run.
+ */
+export declare function getRepoFileOrNull(octokit: GithubClient, owner: string, repo: string, path: string): Promise<null | string>;
 /** Root file/directory names — the compile-manifest gate reads them to tell a
  * directory of resources from a repo that IS the deliverable. A `path: ''`
  * listing is always an array; the single-entry branch defends against a file

package/dist/github.js

@@ -110,6 +110,28 @@ export async function getReadme(octokit, owner, repo, format = 'raw') {
     // still describe the JSON shape - cast to string.
     return response.data;
 }
+/**
+ * One in-repo markdown file, for following a README's links into the source's
+ * content files. Returns null (logged) instead of failing the run: a followed
+ * file is best-effort the way repo-info failures are — only the README fetch
+ * itself can fail the run.
+ */
+export async function getRepoFileOrNull(octokit, owner, repo, path) {
+    try {
+        octokit.log.debug(`Fetching ${owner}/${repo}/${path}`);
+        const { data } = await octokit.rest.repos.getContent({
+            mediaType: { format: 'raw' },
+            owner,
+            path,
+            repo,
+        });
+        return data;
+    }
+    catch (error) {
+        octokit.log.warn(`Failed to fetch ${owner}/${repo}/${path}: ${formatRequestError(error)}`);
+        return null;
+    }
+}
 /** Root file/directory names — the compile-manifest gate reads them to tell a
  * directory of resources from a repo that IS the deliverable. A `path: ''`
  * listing is always an array; the single-entry branch defends against a file
@@ -153,7 +175,17 @@ export function parseOwnerRepo(value) {
     if (parts.length !== 2) {
         return null;
     }
-    return { owner: parts[0], repo: parts[1].replace(/\.git$/, '') };
+    return {
+        owner: stripZeroWidth(parts[0]),
+        repo: stripZeroWidth(parts[1]).replace(/\.git$/, ''),
+    };
+}
+// Zero-width characters glued to a repo name (awesome-computer-vision links
+// neuraltalk with an invisible BOM) are not identity; URL.pathname keeps them
+// percent-encoded, so both spellings are stripped before the name is used.
+const ZERO_WIDTH = /(?:%EF%BB%BF|%E2%80%8[B-F]|%E2%81%A0)|[\u200B-\u200F\u2060\uFEFF]/gi;
+function stripZeroWidth(segment) {
+    return segment.replace(ZERO_WIDTH, '');
 }
 export function parseGitHubUrl(url) {
     try {
@@ -165,7 +197,7 @@ export function parseGitHubUrl(url) {
             .split('/')
             .filter(part => part.length > 0);
         if (pathParts.length >= 2) {
-            const owner = pathParts[0], repo = pathParts[1].replace(/\.git$/, '');
+            const owner = stripZeroWidth(pathParts[0]), repo = stripZeroWidth(pathParts[1]).replace(/\.git$/, '');
             return { owner, repo };
         }
         return null;

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-export { formatRequestError, getLatestCommitSha, getReadme, getRepoInfo, getRepoInfoOrNull, getRootEntryNames, makeOctokit, parseGitHubUrl, parseOwnerRepo, } from './github.js';
+export { formatRequestError, getLatestCommitSha, getReadme, getRepoFileOrNull, getRepoInfo, getRepoInfoOrNull, getRootEntryNames, makeOctokit, parseGitHubUrl, parseOwnerRepo, } from './github.js';
 export type { GithubClient, MakeOctokitOptions, RepoIdentifier, RepoInfoDetails, ThrottleOptions, } from './github.js';
 export type { Logger } from './logger.js';
 export { consoleLog, silentLog } from './logger.js';
-export { toRepoInfo } from './markdown.js';
+export { countItems, hollowsPrevious, toRepoInfo } from './markdown.js';
 export type { JsonGroup, JsonItem, JsonMetadata, JsonNode, JsonOutput, JsonSection, ReplacementRule, RepoInfo, } from './markdown.js';
 export { enhance } from './orchestrator.js';
 export type { EnhanceOptions, EnhanceResult } from './orchestrator.js';

package/dist/index.js

@@ -1,4 +1,4 @@
-export { formatRequestError, getLatestCommitSha, getReadme, getRepoInfo, getRepoInfoOrNull, getRootEntryNames, makeOctokit, parseGitHubUrl, parseOwnerRepo, } from './github.js';
+export { formatRequestError, getLatestCommitSha, getReadme, getRepoFileOrNull, getRepoInfo, getRepoInfoOrNull, getRootEntryNames, makeOctokit, parseGitHubUrl, parseOwnerRepo, } from './github.js';
 export { consoleLog, silentLog } from './logger.js';
-export { toRepoInfo } from './markdown.js';
+export { countItems, hollowsPrevious, toRepoInfo } from './markdown.js';
 export { enhance } from './orchestrator.js';

package/dist/internal-links.d.ts

@@ -0,0 +1,21 @@
+/** Bounds for one follow run: files fetched, and bytes per file. */
+export declare const MAX_FOLLOWED_FILES = 50;
+export declare const MAX_FOLLOWED_FILE_BYTES = 1000000;
+/** True for a resolved repo path that must never be followed or inlined. */
+export declare function isSkippedPath(path: string): boolean;
+/**
+ * Resolves one link target against the referring document's directory.
+ * Accepts repo-relative (`docs/x.md`), referring-file-relative
+ * (`../guides/y.md`) and repo-root-absolute (`/x.md`) forms. Returns null for
+ * anything that is not an in-repo path: external URLs, anchors, non-markdown
+ * files, or `..` escaping the repo root.
+ */
+export declare function resolveRepoPath(target: string, baseDir: string): null | string;
+/**
+ * Extracts the in-repo markdown path from a same-repo absolute GitHub URL
+ * (`https://github.com/owner/repo/blob/main/docs/x.md`), or null for links to
+ * any other host/repo.
+ */
+export declare function parseSameRepoBlobPath(url: string, owner: string, repo: string): null | string;
+/** True when a link's visible text is just a filename/path, not a category name. */
+export declare function isFilenameLabel(label: string, path: string): boolean;

package/dist/internal-links.js

@@ -0,0 +1,112 @@
+// Path rules for following a README's links into other markdown files of the
+// SAME repo — the "content moved out of the README" shape (android-root moved
+// 600+ entries into docs/apps-and-modules/*.md and left a landing page).
+// Pure string/path logic only; fetching and AST splicing live in markdown.ts.
+/** Bounds for one follow run: files fetched, and bytes per file. */
+export const MAX_FOLLOWED_FILES = 50;
+export const MAX_FOLLOWED_FILE_BYTES = 1_000_000;
+const MARKDOWN_EXT = /\.(md|markdown)$/i;
+// Repo-convention meta documents. Only honored at the repo root and under
+// .github/ — elsewhere a same-named file is content: android-root's
+// docs/apps-and-modules/security.md is the Security category, and a basename
+// rule would silently drop it.
+const META_BASENAMES = new Set([
+    'acknowledgements',
+    'acknowledgments',
+    'authors',
+    'changes',
+    'changelog',
+    'citation',
+    'code of conduct',
+    'code_of_conduct',
+    'code-of-conduct',
+    'conduct',
+    'contributing',
+    'contributors',
+    'funding',
+    'history',
+    'issue_template',
+    'license',
+    'licence',
+    'notice',
+    'pull_request_template',
+    'security',
+    'support',
+    'todo',
+]);
+// The root README and its translations/self-links are alternate views of the
+// document being enhanced, never additional content — inlining one would
+// duplicate the whole list. Directory READMEs (pages/RISH.md aside,
+// CLI/README.md shapes) are content and stay followable.
+const ROOT_README = /^readme[^/]*\.(md|markdown)$/i;
+function baseName(path) {
+    const tail = path.slice(path.lastIndexOf('/') + 1);
+    const dot = tail.lastIndexOf('.');
+    return (dot > 0 ? tail.slice(0, dot) : tail).toLowerCase();
+}
+/** True for a resolved repo path that must never be followed or inlined. */
+export function isSkippedPath(path) {
+    if (!MARKDOWN_EXT.test(path)) {
+        return true;
+    }
+    if (!path.includes('/')) {
+        return ROOT_README.test(path) || META_BASENAMES.has(baseName(path));
+    }
+    return path.startsWith('.github/') && META_BASENAMES.has(baseName(path));
+}
+/**
+ * Resolves one link target against the referring document's directory.
+ * Accepts repo-relative (`docs/x.md`), referring-file-relative
+ * (`../guides/y.md`) and repo-root-absolute (`/x.md`) forms. Returns null for
+ * anything that is not an in-repo path: external URLs, anchors, non-markdown
+ * files, or `..` escaping the repo root.
+ */
+export function resolveRepoPath(target, baseDir) {
+    const stripped = target.split('#')[0].split('?')[0].trim();
+    if (!stripped || stripped.includes('://') || stripped.startsWith('mailto:')) {
+        return null;
+    }
+    const segments = (stripped.startsWith('/') ? [] : baseDir.split('/')).concat(stripped.split('/'));
+    const stack = [];
+    for (const segment of segments) {
+        if (segment === '' || segment === '.') {
+            continue;
+        }
+        if (segment === '..') {
+            if (stack.length === 0) {
+                return null;
+            }
+            stack.pop();
+            continue;
+        }
+        stack.push(segment);
+    }
+    return stack.length > 0 ? stack.join('/') : null;
+}
+/**
+ * Extracts the in-repo markdown path from a same-repo absolute GitHub URL
+ * (`https://github.com/owner/repo/blob/main/docs/x.md`), or null for links to
+ * any other host/repo.
+ */
+export function parseSameRepoBlobPath(url, owner, repo) {
+    const match = /^https?:\/\/(?:www\.)?github\.com\/([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)\/(?:blob|raw)\/[^/]+\/(.+)$/i.exec(url);
+    if (!match) {
+        return null;
+    }
+    if (`${match[1]}/${match[2]}`.toLowerCase() !== `${owner}/${repo}`.toLowerCase()) {
+        return null;
+    }
+    return decodeURIComponent(match[3]);
+}
+/** True when a link's visible text is just a filename/path, not a category name. */
+export function isFilenameLabel(label, path) {
+    const text = label.trim().toLowerCase();
+    if (!text) {
+        return true;
+    }
+    const file = path.slice(path.lastIndexOf('/') + 1).toLowerCase();
+    return (text === file ||
+        text === path.toLowerCase() ||
+        text.includes('/') ||
+        MARKDOWN_EXT.test(text));
+}

package/dist/markdown.d.ts

@@ -1,4 +1,4 @@
-import { RepoInfoDetails } from './github.js';
+import { RepoIdentifier, RepoInfoDetails } from './github.js';
 import { Logger } from './logger.js';
 import type { Heading, Link, List, Parent, Root } from 'mdast';
 export interface JsonOutput {
@@ -18,17 +18,17 @@ export interface SortOptions {
 }
 export interface RepoInfo {
     archived: boolean;
-    description: null | string;
-    homepage: null | string;
+    description?: null | string;
+    homepage?: null | string;
     id: number;
     language: null | string;
-    license: null | string;
+    license?: null | string;
     last_commit: null | string;
-    open_issues: number;
+    open_issues?: number;
     owner: string;
     repo: string;
     stars: number;
-    topics: string[];
+    topics?: string[];
 }
 /** The sole crossing from the API shape to the emitted one, so both agree on the renames. */
 export declare function toRepoInfo(details: RepoInfoDetails): RepoInfo;
@@ -37,7 +37,7 @@ export interface JsonItem {
     description: null | string;
     first_seen?: string;
     node_type: 'item';
-    repo_info: RepoInfo;
+    repo_info?: RepoInfo;
     title: string;
 }
 export interface JsonGroup {
@@ -60,7 +60,9 @@ export interface JsonSection {
     items: JsonNode[];
     title: string;
 }
-export declare function processMarkdownContent(originalContent: string, token: string, replacements?: ReplacementRule[], sortOptions?: SortOptions, relativeLinkPrefix?: string, enhancedRepository?: string, enhancedRepositoryDescription?: string, originalRepositorySha?: string, originalRepositoryInfo?: null | RepoInfoDetails, previousJson?: JsonOutput, now?: Date, log?: Logger): Promise<{
+export declare function countItems(output: JsonOutput): number;
+export declare function hollowsPrevious(previous: JsonOutput, next: JsonOutput): boolean;
+export declare function processMarkdownContent(originalContent: string, token: string, replacements?: ReplacementRule[], sortOptions?: SortOptions, relativeLinkPrefix?: string, enhancedRepository?: string, enhancedRepositoryDescription?: string, originalRepositorySha?: string, originalRepositoryInfo?: null | RepoInfoDetails, sourceRepository?: RepoIdentifier, previousJson?: JsonOutput, now?: Date, log?: Logger): Promise<{
     finalContent: string;
     jsonData: JsonOutput;
 }>;

package/dist/markdown.js

@@ -5,7 +5,8 @@ import remarkStringify from 'remark-stringify';
 import { unified } from 'unified';
 import { visit } from 'unist-util-visit';
 import { firstSeenFor } from './first-seen.js';
-import { formatRequestError, getRepoInfo as fetchRepoInfo, makeOctokit, parseGitHubUrl, } from './github.js';
+import { formatRequestError, getRepoFileOrNull, getRepoInfo as fetchRepoInfo, makeOctokit, parseGitHubUrl, } from './github.js';
+import { isFilenameLabel, isSkippedPath, MAX_FOLLOWED_FILE_BYTES, MAX_FOLLOWED_FILES, parseSameRepoBlobPath, resolveRepoPath, } from './internal-links.js';
 import { consoleLog } from './logger.js';
 /** The sole crossing from the API shape to the emitted one, so both agree on the renames. */
 export function toRepoInfo(details) {
@@ -24,6 +25,19 @@ export function toRepoInfo(details) {
         topics: details.topics,
     };
 }
+export function countItems(output) {
+    const count = (nodes) => nodes.reduce((sum, node) => sum + (node.node_type === 'item' ? 1 : 0) + count(node.children), 0);
+    return count(output.items.flatMap(section => section.items));
+}
+// A >95% item collapse against the previous run is a parse regression or a
+// source restructure, never a real edit — the caller refuses to write rather
+// than hollow the mirror (android-root committed a skeleton daily for three
+// days before this guard existed).
+const HOLLOW_SHRINKAGE = 0.05;
+export function hollowsPrevious(previous, next) {
+    const before = countItems(previous);
+    return before > 0 && countItems(next) < before * HOLLOW_SHRINKAGE;
+}
 // The lookup's single throttled client coordinates rate limits across the whole
 // pool, so this bounds in-flight targets rather than requests.
 const FETCH_CONCURRENCY = 10;
@@ -62,9 +76,9 @@ function createRepoInfoLookup(token, log) {
  * collapse to a single fetch inside the lookup, then fan back out to every alias
  * here.
  *
- * Each target's failure is independent and non-fatal: a dead link is skipped
- * with a warning and its item is still emitted (no repo_info). Only the source
- * README fetch in main.ts can fail the run.
+ * Each target's failure is independent and non-fatal: a dead link drops its
+ * entry and lifts the children. Only the source README fetch in main.ts can
+ * fail the run.
  */
 async function fetchTargetData(urls, repos) {
     const log = repos.client.log;
@@ -85,15 +99,169 @@ async function fetchTargetData(urls, repos) {
     log.info(`Target fetch: ${repoInfoMap.size}/${urls.size} repo-info ok in ${Date.now() - fetchStart}ms (concurrency ${FETCH_CONCURRENCY}).`);
     return repoInfoMap;
 }
-export async function processMarkdownContent(originalContent, token, replacements = [], sortOptions = { by: '', minLinks: 2 }, relativeLinkPrefix = '', enhancedRepository, enhancedRepositoryDescription, originalRepositorySha, originalRepositoryInfo, previousJson, now = new Date(), log = consoleLog) {
+// The same-repo markdown links of one document: resolved relative and
+// root-absolute targets, plus same-repo absolute blob/raw URLs. Labels ride
+// along because they become the spliced category's title.
+function collectDocLinks(tree, baseDir, source) {
+    const links = [];
+    visit(tree, 'link', (node) => {
+        const path = resolveRepoPath(node.url, baseDir) ??
+            parseSameRepoBlobPath(node.url, source.owner, source.repo);
+        if (!path || isSkippedPath(path)) {
+            return;
+        }
+        links.push({ label: getInlineText(node.children), path });
+    });
+    return links;
+}
+const FRONTMATTER = /^---\r?\n[\s\S]*?\r?\n---\r?\n?/;
+// VitePress/Docusaurus content files open with YAML frontmatter that remark
+// would misread as a thematic break plus a setext heading.
+function stripFrontmatter(content) {
+    return content.replace(FRONTMATTER, '');
+}
+// Removes the file's leading H1 — the injected category heading replaces it,
+// so the document never carries the same title twice — and returns its text
+// for the filename-label fallback.
+function stripTitleHeading(tree) {
+    const first = tree.children[0];
+    if (first?.type === 'heading' && first.depth === 1) {
+        tree.children.shift();
+        return getNodeText(first);
+    }
+    return '';
+}
+// One level shallower than the file's shallowest remaining heading, so the
+// file's own sections nest inside the category; a heading-less file takes the
+// conventional section level of 2.
+function categoryHeadingDepth(children) {
+    let shallowest = Infinity;
+    for (const node of children) {
+        if (node.type === 'heading') {
+            shallowest = Math.min(shallowest, node.depth);
+        }
+    }
+    // shallowest is 1..6, so the clamped result stays inside the depth union.
+    return shallowest === Infinity
+        ? 2
+        : Math.max(1, shallowest - 1);
+}
+// Relative links and images resolve against the source repo's tree; in the
+// mirror they dangle. Rewritten to GitHub URLs at HEAD.
+function rewriteRelativeLinksToSource(tree, baseDir, source) {
+    const absolute = (url) => {
+        if (!url ||
+            url.startsWith('#') ||
+            url.includes('://') ||
+            url.startsWith('mailto:')) {
+            return url;
+        }
+        const path = resolveRepoPath(url, baseDir);
+        return path
+            ? `https://github.com/${source.owner}/${source.repo}/blob/HEAD/${path}`
+            : url;
+    };
+    visit(tree, 'link', (node) => {
+        node.url = absolute(node.url);
+    });
+    visit(tree, 'image', (node) => {
+        node.url = absolute(node.url);
+    });
+}
+/**
+ * Appends the source's internal markdown files to the tree, each under a
+ * heading titled by its link's text — the README-is-a-landing-page shape.
+ * Breadth-first in document order with a visited set, so a file linked from
+ * both the README and an index page is fetched and spliced once, the README's
+ * label winning. A file joins the document only when it carries at least
+ * `minLinks` GitHub links; navigation pages are still parsed for their links,
+ * which is where this shape often keeps them.
+ */
+async function appendInternalDocs(tree, source, repos, minLinks, log) {
+    const processor = unified().use(remarkParse).use(remarkGfm);
+    const queue = collectDocLinks(tree, '', source);
+    const visited = new Set();
+    const labels = new Map();
+    let fetched = 0;
+    let appended = 0;
+    let processed = 0;
+    while (queue.length > 0 && processed < MAX_FOLLOWED_FILES) {
+        const link = queue.shift();
+        if (visited.has(link.path)) {
+            continue;
+        }
+        processed += 1;
+        visited.add(link.path);
+        if (link.label.trim() && !labels.has(link.path)) {
+            labels.set(link.path, link.label);
+        }
+        const raw = await getRepoFileOrNull(repos.client, source.owner, source.repo, link.path);
+        if (!raw) {
+            continue;
+        }
+        fetched += 1;
+        if (raw.length > MAX_FOLLOWED_FILE_BYTES) {
+            log.warn(`Skipping ${link.path}: over ${MAX_FOLLOWED_FILE_BYTES} bytes.`);
+            continue;
+        }
+        const fileTree = processor.parse(stripFrontmatter(raw));
+        const ownTitle = stripTitleHeading(fileTree);
+        const baseDir = link.path.includes('/')
+            ? link.path.slice(0, link.path.lastIndexOf('/'))
+            : '';
+        for (const nested of collectDocLinks(fileTree, baseDir, source)) {
+            if (!visited.has(nested.path)) {
+                queue.push(nested);
+            }
+        }
+        if (countGitHubRepos(fileTree) < minLinks) {
+            continue;
+        }
+        const label = labels.get(link.path) ?? '';
+        const title = isFilenameLabel(label, link.path)
+            ? ownTitle || label || link.path
+            : label;
+        const heading = {
+            type: 'heading',
+            depth: categoryHeadingDepth(fileTree.children),
+            children: [{ type: 'text', value: title }],
+        };
+        rewriteRelativeLinksToSource(fileTree, baseDir, source);
+        tree.children.push(heading, ...fileTree.children);
+        appended += 1;
+    }
+    rewriteRelativeLinksToSource(tree, '', source);
+    log.info(`README skeleton: followed ${fetched} internal file(s), appended ${appended} as categories.`);
+}
+export async function processMarkdownContent(originalContent, token, replacements = [], sortOptions = { by: '', minLinks: 2 }, relativeLinkPrefix = '', enhancedRepository, enhancedRepositoryDescription, originalRepositorySha, originalRepositoryInfo, sourceRepository, previousJson, now = new Date(), log = consoleLog) {
     const repos = createRepoInfoLookup(token, log);
     const brandingEnabled = replacements.some(rule => rule.type === 'branding');
     const contentAfterReplacements = applyTextReplacements(originalContent, replacements.filter(rule => rule.type !== 'branding'), log);
     const processor = unified().use(remarkParse).use(remarkGfm);
     const tree = processor.parse(contentAfterReplacements);
     normalizeGitHubUrls(tree);
+    // A README too thin to carry the list is a landing page: the content lives
+    // in the files it links. Splice them in before anything reads the tree, so
+    // the repo fetch, badges and the section walk all see the combined document.
+    if (sourceRepository && countGitHubRepos(tree) < sortOptions.minLinks) {
+        await appendInternalDocs(tree, sourceRepository, repos, sortOptions.minLinks, log);
+        normalizeGitHubUrls(tree);
+    }
     const githubUrls = collectGitHubLinks(tree);
-    const repoInfoMap = await fetchTargetData(githubUrls, repos);
+    // Links into the source repository itself are navigation — its doc pages,
+    // its contributing links — never entries. android-root's index links every
+    // category page, and each of those links would borrow the source repo's
+    // identity and emit an item for it. Excluding the source from the target
+    // fetch leaves every emission path reading such a link as a dead one: no
+    // item, children lifted, the row left in markdown.
+    const targetUrls = sourceRepository &&
+        new Set([...githubUrls].filter(url => {
+            const id = parseGitHubUrl(url);
+            return !(id &&
+                `${id.owner}/${id.repo}`.toLowerCase() ===
+                    `${sourceRepository.owner}/${sourceRepository.repo}`.toLowerCase());
+        }));
+    const repoInfoMap = await fetchTargetData(targetUrls ?? githubUrls, repos);
     const firstSeen = firstSeenFor(previousJson, now);
     const { sections, title: rawTitle, titleHeadingIndex, } = processTree(tree, repoInfoMap, sortOptions, originalRepositoryInfo, firstSeen);
     // Single source of truth for the document title: brand it once and use the
@@ -181,8 +349,31 @@ function collectGitHubLinks(tree) {
             urls.add(node.url);
         }
     });
+    // A details summary's anchor stays raw html (normalizeGitHubUrls leaves
+    // block html alone), so the identity it names joins the fetch set here;
+    // the summary promotion looks the repo up by the same href.
+    visit(tree, 'html', (node) => {
+        const identity = parseDetailsSummary(node.value)?.identity;
+        if (identity) {
+            urls.add(identity.url);
+        }
+    });
     return urls;
 }
+// The number of distinct GitHub REPOS a document addresses — the census unit
+// for both the skeleton trigger and the splice gate. Distinct URLs would
+// overcount: a skeleton README badges the source repo and links its issues
+// page, which is two URLs over one repo.
+function countGitHubRepos(tree) {
+    const repos = new Set();
+    visit(tree, 'link', (node) => {
+        const id = parseGitHubUrl(node.url);
+        if (id) {
+            repos.add(`${id.owner}/${id.repo}`.toLowerCase());
+        }
+    });
+    return repos.size;
+}
 // Input normalization, same family as fixRelativeLinks: make GitHub repos a
 // source expresses WITHOUT markdown links visible as real link nodes, so
 // every downstream consumer — repo fetch, entry tests, gates, badges — sees
@@ -478,10 +669,14 @@ function processListRecursively(listNode, repoInfoMap, sortOptions, firstSeen, i
 // The caller's section-scope gate decision (sectionGatePasses). Absent for
 // nested lists (emitted under their parent regardless) and for top-level
 // lists with no open container (preamble), which gate per list.
-sectionGateOpen) {
+sectionGateOpen, 
+// The promoted details-item this list sits directly inside: an entry
+// restating that repo (the best-of "GitHub" bullet) is the entry the
+// summary already emitted, not a second item — its children still lift,
+// the way a dead link's do.
+suppressRepo) {
     if (!isNested) {
-        const gateOpen = sectionGateOpen ??
-            countLinkedItems(listNode) >= sortOptions.minLinks;
+        const gateOpen = sectionGateOpen ?? countLinkedItems(listNode) >= sortOptions.minLinks;
         if (!gateOpen) {
             return [];
         }
@@ -503,6 +698,10 @@ sectionGateOpen) {
         const childrenJson = nestedContent.flatMap(child => child.type === 'list'
             ? processListRecursively(child, repoInfoMap, sortOptions, firstSeen, true)
             : processTableRows(child, repoInfoMap, true, firstSeen));
+        if (suppressRepo && repoInfo === suppressRepo) {
+            entries.push({ emitted: childrenJson, node: itemNode, repoInfo });
+            continue;
+        }
         // Title/description split on the FIRST paragraph only — a paper-list
         // entry's identity link may live in a later paragraph (findOwnGitHubLink)
         // while its title text stays the leading one.
@@ -516,6 +715,7 @@ sectionGateOpen) {
         // The shared title fallbacks (an inline-code link label carries no text
         // nodes, so the split alone can leave an empty title).
         entryText.title = entryTitle(entryText.title, ownLink, repoInfo);
+        entryText.description = entryDescription(entryText.description, repoInfo);
         const emitted = emitEntryNodes(githubUrl, repoInfo, entryText, childrenJson, firstSeen);
         entries.push({ emitted, node: itemNode, repoInfo });
     }
@@ -544,6 +744,23 @@ function entryTitle(base, ownLink, repoInfo) {
     }
     return repoInfo ? `${repoInfo.owner}/${repoInfo.repo}` : base;
 }
+// Description with the fallback every entry source shares: the split's own
+// trailing prose when it says something — minus a leading badge cluster —
+// else — for a live repo link — owner/name. The own link's label is never
+// consulted: in the corpus it only ever echoes the title back (":tada:
+// Doom" already says "Doom"). A degenerate base with no live repo link (a
+// group) keeps its text: nothing better exists.
+function entryDescription(base, repoInfo) {
+    // The noise strip runs only behind a stripped cluster: a bare leading
+    // dash or colon can be a word's own (the table paths never noise-stripped
+    // their cells, and "-equivalent" / ":bird:" descriptions are real).
+    const withoutBadges = stripBadgeClusters(base);
+    const stripped = withoutBadges === base ? base : stripLeadingNoise(withoutBadges);
+    if (!isDegenerateDescription(stripped)) {
+        return stripped;
+    }
+    return repoInfo ? `${repoInfo.owner}/${repoInfo.repo}` : stripped;
+}
 function processTableRows(tableNode, repoInfoMap, gateOpen, firstSeen) {
     if (!gateOpen) {
         return [];
@@ -583,9 +800,10 @@ function processTableRows(tableNode, repoInfoMap, gateOpen, firstSeen) {
             ]
                 .join(' ')
                 .trim();
+            const title = entryTitle(titleText.title, ownLink, repoInfo);
             items.push(...emitEntryNodes(ownLink.url, repoInfo, {
-                title: entryTitle(titleText.title, ownLink, repoInfo),
-                description,
+                title,
+                description: entryDescription(description, repoInfo),
             }, [], firstSeen));
             continue;
         }
@@ -597,9 +815,10 @@ function processTableRows(tableNode, repoInfoMap, gateOpen, firstSeen) {
             emittedUrls.add(ownLink.url);
             const repoInfo = repoInfoMap.get(ownLink.url) ?? null;
             const cellText = splitEntryText(row.children[cellIndex].children);
+            const title = entryTitle(cellText.title, ownLink, repoInfo);
             items.push(...emitEntryNodes(ownLink.url, repoInfo, {
-                title: entryTitle(cellText.title, ownLink, repoInfo),
-                description: cellText.description,
+                title,
+                description: entryDescription(cellText.description, repoInfo),
             }, [], firstSeen));
         }
     }
@@ -620,6 +839,13 @@ function isDegenerateTitle(title) {
 function isMeaningfulLinkText(text) {
     return text !== '' && !isDegenerateTitle(text);
 }
+// Description-only tag words beyond the title set: the second-link label
+// families the corpus census measured ("website", "documentation", …).
+const DESC_TAG_TEXT = /^(?:website|homepage|home\s+page|link|here|documentation|repository)$/i;
+function isDegenerateDescription(description) {
+    const trimmed = description.trim();
+    return (trimmed === '' || DESC_TAG_TEXT.test(trimmed) || isDegenerateTitle(trimmed));
+}
 // Dated entry lines end their tag cluster with a publication date ("4 Feb
 // 2023", "19 Apr 2022", "2023") — a real corpus family (dated paper/tutorial
 // lists), not a sentence continuation.
@@ -735,9 +961,10 @@ function blockquoteEntries(blockquote) {
 function entryNodesFor(ownLink, inlines, repoInfoMap, firstSeen) {
     const repoInfo = repoInfoMap.get(ownLink.url) ?? null;
     const entryText = splitEntryText(inlines);
+    const title = entryTitle(entryText.title, ownLink, repoInfo);
     return emitEntryNodes(ownLink.url, repoInfo, {
-        title: entryTitle(entryText.title, ownLink, repoInfo),
-        description: entryText.description,
+        title,
+        description: entryDescription(entryText.description, repoInfo),
     }, [], firstSeen);
 }
 // The <details><summary>…</summary> collapsible-section idiom: the summary
@@ -747,17 +974,54 @@ function entryNodesFor(ownLink, inlines, repoInfoMap, firstSeen) {
 // no summary, or an empty one, delimits nothing.
 const DETAILS_SUMMARY = /<details[^>]*>[\s\S]*?<summary[^>]*>([\s\S]*?)<\/summary>/i;
 const DETAILS_CLOSE = /^\s*<\/details>/i;
-function detailsSummaryTitle(htmlValue) {
+// One summary's read of the walk: the summary's whole text (the container
+// title when the block is not an entry), and — when the summary carries the
+// entry's identity (the best-of generator's shape: repo anchor, badge
+// cluster, curated sentence) — that anchor and the prose trailing it.
+const SUMMARY_ANCHOR = /<a\s[^>]*href=(["'])([^"']*)\1[^>]*>([\s\S]*?)<\/a>/gi;
+function summaryHtmlText(html) {
+    return html
+        .replace(/<[^>]+>/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+function parseDetailsSummary(htmlValue) {
     const match = DETAILS_SUMMARY.exec(htmlValue);
     if (!match) {
         return null;
     }
-    const title = match[1]
+    const inner = match[1];
+    const title = inner
         .replace(/<kbd>[\s\S]*?<\/kbd>/gi, '')
         .replace(/<[^>]+>/g, ' ')
         .replace(/\s+/g, ' ')
         .trim();
-    return title || null;
+    let identity = null;
+    let prose = '';
+    for (const anchor of inner.matchAll(SUMMARY_ANCHOR)) {
+        if (!parseGitHubUrl(anchor[2])) {
+            continue;
+        }
+        identity = { label: summaryHtmlText(anchor[3]), url: anchor[2] };
+        prose = summaryHtmlText(inner.slice((anchor.index ?? 0) + anchor[0].length));
+        break;
+    }
+    return { identity, prose, title: title || null };
+}
+function detailsSummaryTitle(htmlValue) {
+    return parseDetailsSummary(htmlValue)?.title ?? null;
+}
+// A badge cluster from a generated summary: a parenthesized run of medals,
+// counts and size suffixes (🥈31 · ⭐ 1.9K) — symbols, digits and punctuation,
+// no words, at least one of them. A parenthetical with any other letter (an
+// aside in prose) or an empty pair () stays.
+const BADGE_CLUSTER = /^\([\p{P}\p{S}\p{N}\sKMG]+\)\s*/u;
+function stripBadgeClusters(text) {
+    let out = text.trimStart();
+    while (BADGE_CLUSTER.test(out)) {
+        out = out.replace(BADGE_CLUSTER, '');
+    }
+    return out;
 }
 // The summary text of a <details><summary> block inside a list item, when the
 // item has no paragraph text of its own.
@@ -910,7 +1174,7 @@ function processTree(tree, repoInfoMap, sortOptions, originalRepositoryInfo, fir
     // comparison holds even for aliased spellings.
     const rementionsOpenItem = (link) => {
         const repoInfo = repoInfoMap.get(link.url);
-        return !!repoInfo && stack.some(container => container.repoInfo === repoInfo);
+        return (!!repoInfo && stack.some(container => container.repoInfo === repoInfo));
     };
     for (let i = 0; i < tree.children.length; i++) {
         const node = tree.children[i];
@@ -933,7 +1197,9 @@ function processTree(tree, repoInfoMap, sortOptions, originalRepositoryInfo, fir
         else if (node.type === 'paragraph') {
             const text = getNodeText(node);
             // Boilerplate "back to top" lines are neither entries nor description.
-            const ownLink = BACK_TO_TOP.test(text) ? undefined : paragraphEntryLink(node);
+            const ownLink = BACK_TO_TOP.test(text)
+                ? undefined
+                : paragraphEntryLink(node);
             // An entry paragraph behaves like a one-item list; a failed gate, a
             // dead target, or a re-mention of the enclosing item leaves plain
             // description.
@@ -943,7 +1209,10 @@ function processTree(tree, repoInfoMap, sortOptions, originalRepositoryInfo, fir
             else {
                 const container = stack[stack.length - 1];
                 // Avoid adding boilerplate "back to top" links to descriptions.
-                if (container && text && !BACK_TO_TOP.test(text)) {
+                if (container &&
+                    text &&
+                    !BACK_TO_TOP.test(text) &&
+                    collectsProse(container)) {
                     container.description = container.description
                         ? `${container.description}\n${text}`
                         : text;
@@ -966,7 +1235,10 @@ function processTree(tree, repoInfoMap, sortOptions, originalRepositoryInfo, fir
             else {
                 const container = stack[stack.length - 1];
                 // Avoid adding boilerplate "back to top" links to descriptions.
-                if (container && text && !BACK_TO_TOP.test(text)) {
+                if (container &&
+                    text &&
+                    !BACK_TO_TOP.test(text) &&
+                    collectsProse(container)) {
                     container.description = container.description
                         ? `${container.description}\n${text}`
                         : text;
@@ -974,30 +1246,61 @@ function processTree(tree, repoInfoMap, sortOptions, originalRepositoryInfo, fir
             }
         }
         else if (node.type === 'html') {
-            // A details-summary block opens a section like a heading would; the
-            // close tag (or the next summary) ends it — never the enclosing
-            // section, which keeps collecting after the collapsible block.
-            const summaryTitle = detailsSummaryTitle(node.value);
-            if (summaryTitle) {
+            // A details-summary block is the entry itself when its summary carries
+            // the identity (the best-of generator's shape) — promoted exactly like
+            // a link-bearing heading, so the entry nests in its real category with
+            // the summary's curated sentence as its description and the badges
+            // gone. Any other summary opens a container like a heading would: a
+            // group under the open container (the JSON has no nested sections), a
+            // section at document level. The close tag (or the next summary) ends
+            // it — never the enclosing section, which keeps collecting after the
+            // collapsible block.
+            const summary = parseDetailsSummary(node.value);
+            if (summary) {
                 closeInnermostDetails(stack, sectionRecords, firstSeen);
                 // Container depths never decrease going up the stack. When the open
                 // containers sit deeper than sectionDepth (a mid-document H1 defines
-                // sectionDepth while the content sections run deeper), the
-                // details-section joins at the current depth — pushing at the
-                // shallower sectionDepth would invert the stack and strand the gate
-                // (which reads the stack bottom) on a tiny outer section.
+                // sectionDepth while the content sections run deeper), the container
+                // joins at the current depth — pushing at the shallower sectionDepth
+                // would invert the stack and strand the gate (which reads the stack
+                // bottom) on a tiny outer section.
                 const joinDepth = stack.length === 0
                     ? sectionDepth
                     : Math.max(sectionDepth, stack[stack.length - 1].headingDepth);
-                stack.push({
-                    children: [],
-                    description: '',
-                    headingDepth: joinDepth,
-                    headingIndex: i,
-                    kind: 'section',
-                    openedByDetails: true,
-                    title: summaryTitle,
-                });
+                const repoInfo = summary.identity
+                    ? (repoInfoMap.get(summary.identity.url) ?? null)
+                    : null;
+                const promoted = summary.identity &&
+                    repoInfo &&
+                    isMeaningfulLinkText(summary.identity.label)
+                    ? { identity: summary.identity, repoInfo }
+                    : null;
+                if (promoted && stack.length === 0) {
+                    openSynthesizedSection(stack, i, sectionDepth);
+                }
+                if (promoted && gateForSection(stack[0])) {
+                    stack.push({
+                        children: [],
+                        description: entryDescription(summary.prose, promoted.repoInfo),
+                        headingDepth: joinDepth,
+                        headingIndex: i,
+                        kind: 'item',
+                        openedByDetails: true,
+                        repoInfo: promoted.repoInfo,
+                        title: promoted.identity.label,
+                    });
+                }
+                else {
+                    stack.push({
+                        children: [],
+                        description: '',
+                        headingDepth: joinDepth,
+                        headingIndex: i,
+                        kind: stack.length === 0 ? 'section' : 'group',
+                        openedByDetails: true,
+                        title: summary.title ?? '',
+                    });
+                }
             }
             else if (DETAILS_CLOSE.test(node.value)) {
                 closeInnermostDetails(stack, sectionRecords, firstSeen);
@@ -1013,8 +1316,13 @@ function processTree(tree, repoInfoMap, sortOptions, originalRepositoryInfo, fir
             }
             // Every list inside the open container contributes items — a section is
             // not closed by its first list — and the minLinks gate is decided per
-            // section, against the whole section subtree.
-            const items = processListRecursively(node, repoInfoMap, sortOptions, firstSeen, false, gateForSection(stack[0]));
+            // section, against the whole section subtree. A list directly inside a
+            // promoted details-item suppresses the re-mention of that item's repo.
+            const innermost = stack[stack.length - 1];
+            const suppress = innermost.kind === 'item' && innermost.openedByDetails
+                ? innermost.repoInfo
+                : undefined;
+            const items = processListRecursively(node, repoInfoMap, sortOptions, firstSeen, false, gateForSection(stack[0]), suppress);
             stack[stack.length - 1].children.push(...items);
         }
         else if (node.type === 'table') {
@@ -1034,6 +1342,12 @@ function processTree(tree, repoInfoMap, sortOptions, originalRepositoryInfo, fir
         .map(record => record.section);
     return { sections, title: documentTitle, titleHeadingIndex };
 }
+// A details-promoted item's description is the summary's curated sentence;
+// prose inside the collapsible body is the card's content, not more
+// description.
+function collectsProse(container) {
+    return container.kind !== 'item' || !container.openedByDetails;
+}
 // The heading depth that opens top-level sections: the shallowest structural
 // heading in the document other than the title slot. H1s count — ~20% of
 // mirror READMEs use `# Section` after the title H1, and hardcoding H2 would
@@ -1297,7 +1611,11 @@ function finalizeContainer(container, stack, sectionRecords, firstSeen) {
     if (container.kind === 'section') {
         sectionRecords.push({
             headingIndex: container.headingIndex,
-            section: { description, items: container.children, title: container.title },
+            section: {
+                description,
+                items: container.children,
+                title: container.title,
+            },
         });
         return;
     }
@@ -1328,8 +1646,7 @@ function finalizeContainer(container, stack, sectionRecords, firstSeen) {
 // entry heading triggers must stop at the synthesized section wrapping its
 // run — the next entry heading of the run lands back inside it.
 function closeContainers(stack, depth, sectionRecords, firstSeen, stopAtSynthesized = false) {
-    while (stack.length > 0 &&
-        stack[stack.length - 1].headingDepth >= depth) {
+    while (stack.length > 0 && stack[stack.length - 1].headingDepth >= depth) {
         if (stopAtSynthesized && stack[stack.length - 1].openedBySynthesis) {
             break;
         }

package/dist/orchestrator.d.ts

@@ -1,5 +1,5 @@
 import { Logger } from './logger.js';
-import type { RepoInfoDetails } from './github.js';
+import type { RepoInfoDetails, RepoIdentifier } from './github.js';
 import { JsonOutput, ReplacementRule } from './markdown.js';
 export interface EnhanceOptions {
     content: string;
@@ -14,6 +14,7 @@ export interface EnhanceOptions {
     relativeLinkPrefix?: string;
     replacements?: ReplacementRule[];
     sortBy?: '' | 'last_commit' | 'stars';
+    sourceRepository?: RepoIdentifier;
     token: string;
 }
 export interface EnhanceResult {

package/dist/orchestrator.js

@@ -1,6 +1,6 @@
 import { processMarkdownContent, } from './markdown.js';
 export async function enhance(options) {
-    const { content, disableBranding = false, log, now = new Date(), originalRepositoryInfo, originalRepositorySha, previousJson, relativeLinkPrefix = '', replacements = [], sortBy = '', enhancedRepository, enhancedRepositoryDescription, token, } = options;
+    const { content, disableBranding = false, log, now = new Date(), originalRepositoryInfo, originalRepositorySha, previousJson, relativeLinkPrefix = '', replacements = [], sortBy = '', sourceRepository, enhancedRepository, enhancedRepositoryDescription, token, } = options;
     // Branding is an internal rule prepended to the caller's own; build a fresh
     // array so the caller's `replacements` is never mutated.
     const branding = { type: 'branding' };
@@ -9,7 +9,7 @@ export async function enhance(options) {
         by: sortBy,
         minLinks: 2,
     };
-    const { finalContent, jsonData } = await processMarkdownContent(content, token, rules, sortOptions, relativeLinkPrefix, enhancedRepository, enhancedRepositoryDescription, originalRepositorySha, originalRepositoryInfo, previousJson, now, log);
+    const { finalContent, jsonData } = await processMarkdownContent(content, token, rules, sortOptions, relativeLinkPrefix, enhancedRepository, enhancedRepositoryDescription, originalRepositorySha, originalRepositoryInfo, sourceRepository, previousJson, now, log);
     return {
         finalContent,
         jsonData,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enhansome/core",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "description": "Library core for enhansome — enhance markdown with GitHub star counts.",
   "repository": {
     "type": "git",