@enhansome/core 1.8.0 → 1.9.0

package/dist/github.d.ts

@@ -76,6 +76,12 @@ export interface MakeOctokitOptions {
  */
 export declare function makeOctokit(token: string, { log, maxRetries, maxWaitSeconds, throttle, }?: MakeOctokitOptions): GithubClient;
 export declare function getRepoInfo(octokit: GithubClient, owner: string, repo: string): Promise<RepoInfoDetails>;
+/**
+ * The repo's numeric GitHub id, for the JSON metadata — consumers key stable
+ * node ids on it. Returns null (logged) instead of failing the run: the id is
+ * metadata, not a gate; consumers fall back when it is missing.
+ */
+export declare function getRepoId(octokit: GithubClient, owner: string, repo: string): Promise<null | number>;
 export declare function getReadme(octokit: GithubClient, owner: string, repo: string, format?: 'html' | 'raw'): Promise<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: ''`

package/dist/github.js

@@ -82,6 +82,20 @@ export async function getRepoInfo(octokit, owner, repo) {
         topics: data.topics ?? [],
     };
 }
+/**
+ * The repo's numeric GitHub id, for the JSON metadata — consumers key stable
+ * node ids on it. Returns null (logged) instead of failing the run: the id is
+ * metadata, not a gate; consumers fall back when it is missing.
+ */
+export async function getRepoId(octokit, owner, repo) {
+    try {
+        return (await getRepoInfo(octokit, owner, repo)).id;
+    }
+    catch (error) {
+        octokit.log.error(`Failed to fetch repo id for ${owner}/${repo}: ${formatRequestError(error)}`);
+        return null;
+    }
+}
 export async function getReadme(octokit, owner, repo, format = 'raw') {
     octokit.log.debug(`Fetching ${format} README for ${owner}/${repo}`);
     const response = await octokit.rest.repos.getReadme({

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { formatRequestError, getLatestCommitSha, getReadme, getRepoInfo, getRootEntryNames, makeOctokit, parseGitHubUrl, parseOwnerRepo, } from './github.js';
+export { formatRequestError, getLatestCommitSha, getReadme, getRepoId, getRepoInfo, 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';

package/dist/index.js

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

package/dist/markdown.d.ts

@@ -1,5 +1,6 @@
 import { RepoInfoDetails } from './github.js';
 import { Logger } from './logger.js';
+import type { Heading, Link, List, Parent, Root } from 'mdast';
 export interface JsonOutput {
     items: JsonSection[];
     metadata: JsonMetadata;
@@ -45,6 +46,7 @@ export interface JsonMetadata {
     enhanced_repository_description: null | string;
     last_updated: string;
     original_repository: string;
+    original_repository_id: null | number;
     original_repository_sha: null | string;
     title: string;
 }
@@ -53,7 +55,12 @@ export interface JsonSection {
     items: JsonNode[];
     title: string;
 }
-export declare function processMarkdownContent(originalContent: string, token: string, replacements: ReplacementRule[] | undefined, sortOptions: SortOptions | undefined, originalRepository: string, relativeLinkPrefix?: string, enhancedRepository?: string, enhancedRepositoryDescription?: string, originalRepositorySha?: string, now?: Date, log?: Logger): Promise<{
+export declare function processMarkdownContent(originalContent: string, token: string, replacements: ReplacementRule[] | undefined, sortOptions: SortOptions | undefined, originalRepository: string, relativeLinkPrefix?: string, enhancedRepository?: string, enhancedRepositoryDescription?: string, originalRepositorySha?: string, originalRepositoryId?: number, now?: Date, log?: Logger): Promise<{
     finalContent: string;
     jsonData: JsonOutput;
 }>;
+export declare function normalizeGitHubUrls(tree: Root): void;
+export declare function findFirstGitHubLink(node: Parent): Link | undefined;
+export declare function countLinkedItems(listNode: List): number;
+export declare function isStructuralHeading(node: Heading): boolean;
+export declare function findTitleSlotIndex(tree: Root): number;

package/dist/markdown.js

@@ -79,12 +79,13 @@ 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 }, originalRepository, relativeLinkPrefix = '', enhancedRepository, enhancedRepositoryDescription, originalRepositorySha, now = new Date(), log = consoleLog) {
+export async function processMarkdownContent(originalContent, token, replacements = [], sortOptions = { by: '', minLinks: 2 }, originalRepository, relativeLinkPrefix = '', enhancedRepository, enhancedRepositoryDescription, originalRepositorySha, originalRepositoryId, 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);
     const githubUrls = collectGitHubLinks(tree);
     const repoInfoMap = await fetchTargetData(githubUrls, repos);
     // The title derives from the *source* repository (originalRepository), never
@@ -99,6 +100,7 @@ export async function processMarkdownContent(originalContent, token, replacement
     const metadata = {
         last_updated: now.toISOString(),
         original_repository: originalRepository.trim(),
+        original_repository_id: originalRepositoryId ?? null,
         original_repository_sha: (originalRepositorySha?.trim() ?? '') || null,
         enhanced_repository: (enhancedRepository?.trim() ?? '') || null,
         enhanced_repository_description: (enhancedRepositoryDescription?.trim() ?? '') || null,
@@ -175,6 +177,112 @@ function collectGitHubLinks(tree) {
     });
     return urls;
 }
+// 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
+// the shape a markdown link would have produced. Two families:
+//
+// (1) Bare scheme-less `github.com/owner/repo` text — GFM autolinks only
+//     scheme-full URLs, so these stay plain text. The link's label is the
+//     URL text; only owner/repo are consumed (a deeper path like `/tree/main`
+//     stays in the trailing text — the identity reads the first two segments
+//     either way).
+// (2) Inline `<a href="…">…</a>` anchors — remark emits the open and close
+//     tags as separate html nodes around the label's inline nodes, so the
+//     pair is rewrapped as one link. Anchors inside BLOCK html (`<details>`
+//     summaries, centered banners) keep their raw form: that html is the
+//     structure the walk already reads (detailsSummaryTitle), and rewriting
+//     it is a different decision than link visibility.
+//
+// Text inside code spans/blocks never linkifies (code has no text nodes) and
+// text inside an existing link label is skipped — nested links are not a
+// thing. Non-GitHub and org-only anchors stay raw html.
+const BARE_GITHUB_URL = /(?:^|(?<=[\s(>\[]))(?:www\.)?github\.com\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+/g;
+const ANCHOR_OPEN = /^<a\s[^>]*href=(["'])([^"']*)\1[^>]*>$/;
+const ANCHOR_CLOSE = /^<\/a\s*>$/;
+export function normalizeGitHubUrls(tree) {
+    const walk = (node, inLink) => {
+        if (inLink) {
+            return;
+        }
+        const parent = node;
+        if (!Array.isArray(parent.children)) {
+            return;
+        }
+        for (const child of parent.children) {
+            walk(child, child.type === 'link');
+        }
+        parent.children = normalizeInlineChildren(parent.children);
+    };
+    walk(tree, false);
+}
+// One parent's inline run: bare-URL text nodes split into text/link/text,
+// anchor open+close pairs rewrapped as a link. The anchor's inner nodes are
+// taken verbatim — they are the label, and splitting them would nest links.
+function normalizeInlineChildren(children) {
+    const out = [];
+    for (let i = 0; i < children.length; i++) {
+        const child = children[i];
+        if (child.type === 'html') {
+            const anchor = ANCHOR_OPEN.exec(child.value.trim());
+            const url = anchor && parseGitHubUrl(anchor[2]) ? anchor[2] : null;
+            if (url) {
+                const closeIndex = children.findIndex((candidate, j) => j > i &&
+                    candidate.type === 'html' &&
+                    ANCHOR_CLOSE.test(candidate.value.trim()));
+                if (closeIndex !== -1) {
+                    out.push({
+                        type: 'link',
+                        url,
+                        children: children.slice(i + 1, closeIndex),
+                    });
+                    i = closeIndex;
+                    continue;
+                }
+            }
+            out.push(child);
+            continue;
+        }
+        if (child.type === 'text') {
+            out.push(...linkifyBareUrls(child));
+            continue;
+        }
+        out.push(child);
+    }
+    return out;
+}
+function linkifyBareUrls(node) {
+    const matches = [...node.value.matchAll(BARE_GITHUB_URL)];
+    if (matches.length === 0) {
+        return [node];
+    }
+    const out = [];
+    let cursor = 0;
+    for (const match of matches) {
+        const label = match[0].replace(/\.+$/, '');
+        const url = `https://${label.replace(/^www\./, '')}`;
+        if (!parseGitHubUrl(url)) {
+            continue;
+        }
+        const start = match.index;
+        if (start > cursor) {
+            out.push({
+                type: 'text',
+                value: node.value.slice(cursor, start),
+            });
+        }
+        out.push({
+            type: 'link',
+            url,
+            children: [{ type: 'text', value: label }],
+        });
+        cursor = start + label.length;
+    }
+    if (cursor < node.value.length) {
+        out.push({ type: 'text', value: node.value.slice(cursor) });
+    }
+    return out;
+}
 function createBadgeText(info) {
     if (info.archived) {
         return ' ⚠️ Archived';
@@ -191,27 +299,41 @@ function createBadgeText(info) {
     }
     return ` ${parts.join(' | ')}`;
 }
-function findFirstGitHubLink(node) {
-    let linkUrl;
-    visit(node, 'link', (linkNode) => {
-        if (!linkUrl && parseGitHubUrl(linkNode.url)) {
-            linkUrl = linkNode.url;
+// The first link in a subtree that points at a GitHub repo. Returns the link
+// node itself so callers can take both its URL (identity) and its text
+// (title fallbacks).
+export function findFirstGitHubLink(node) {
+    let linkNode;
+    visit(node, 'link', (candidate) => {
+        if (!linkNode && parseGitHubUrl(candidate.url)) {
+            linkNode = candidate;
         }
     });
-    return linkUrl;
+    return linkNode;
 }
 // The GitHub link that represents a list item: the FIRST GitHub link in the
-// item's OWN paragraph only. A nested-descendant link is deliberately ignored
-// — it belongs to a child, not to this item. An item is a GitHub node iff its
-// own paragraph links to a GitHub repo; an item with no own GitHub link but
+// item's OWN paragraphs, in document order. Paper-list entries carry their
+// identity link ([[Code]](github)) in a paragraph after the title one, so
+// every own paragraph is scanned — the title still comes from the first
+// paragraph alone. A nested-descendant link is deliberately ignored — it
+// belongs to a child, not to this item. An item is a GitHub node iff its own
+// paragraphs link to a GitHub repo; an item with no own GitHub link but
 // nested GitHub children is a group, not a node borrowing a child's identity.
 //
-// A GitHub link that is secondary within the paragraph (e.g.
+// A GitHub link that is secondary within a paragraph (e.g.
 // `[name](marketplace) … [On GitHub](github)`) is still the item's own link, so
 // `findFirstGitHubLink` over the paragraph finds it correctly.
 function findOwnGitHubLink(itemNode) {
-    const paragraph = itemNode.children.find((child) => child.type === 'paragraph');
-    return paragraph ? findFirstGitHubLink(paragraph) : undefined;
+    for (const child of itemNode.children) {
+        if (child.type !== 'paragraph') {
+            continue;
+        }
+        const link = findFirstGitHubLink(child);
+        if (link) {
+            return link;
+        }
+    }
+    return undefined;
 }
 function fixRelativeLinks(tree, relativeLinkPrefix) {
     if (!relativeLinkPrefix) {
@@ -273,15 +395,89 @@ function compareByRepoInfo(by, a, b) {
     const timeB = b.pushed_at ? new Date(b.pushed_at).getTime() : 0;
     return timeB - timeA;
 }
-function processListRecursively(listNode, repoInfoMap, sortOptions, isNested = false) {
-    // The section-sparsity gate counts items whose SUBTREE contains a GitHub
-    // link, not items with an own-paragraph link only. A category with no own
-    // link but nested GitHub children still counts (it becomes a group);
-    // switching to `findOwnGitHubLink` would silently drop purely categorical
-    // sections, so it deliberately diverges from the identity resolver below.
-    const itemsWithGitHubLinks = listNode.children.filter(item => !!findFirstGitHubLink(item));
-    if (!isNested && itemsWithGitHubLinks.length < sortOptions.minLinks) {
-        return [];
+// The minLinks noise gate counts items whose SUBTREE contains a GitHub link,
+// not items with an own-paragraph link only. A category with no own link but
+// nested GitHub children still counts (it becomes a group); switching to
+// `findOwnGitHubLink` would silently drop purely categorical sections, so it
+// deliberately diverges from the identity resolver.
+export function countLinkedItems(listNode) {
+    return listNode.children.filter(item => !!findFirstGitHubLink(item)).length;
+}
+// The table counterpart of countLinkedItems for the section gate: rows whose
+// subtree contains a GitHub link. No header-row skip — a card grid's first row
+// sits above the delimiter and is content, while pure-label header rows carry
+// no links and count zero either way.
+function countLinkedRows(tableNode) {
+    return tableNode.children.filter(row => row.type === 'tableRow' && !!findFirstGitHubLink(row)).length;
+}
+// One entry's title and description, split from its own inlines: leading text
+// up to and including the first link is the title (prefix tags like
+// "[UPDATED]" survive), the prose trailing it the description. The link is
+// found through emphasis wrappers — a bolded card link
+// (`**[Name](repo)** - description`) splits like a plain one. With no link
+// the whole text is the title — the description must never echo the title
+// back.
+function splitEntryText(inlines) {
+    const linkIndex = inlines.findIndex(child => {
+        let hasLink = false;
+        visit(child, 'link', () => {
+            hasLink = true;
+        });
+        return hasLink;
+    });
+    if (linkIndex === -1) {
+        return { title: getInlineText(inlines), description: '' };
+    }
+    return {
+        title: getInlineText(inlines.slice(0, linkIndex + 1)),
+        description: stripLeadingNoise(getInlineText(inlines.slice(linkIndex + 1))),
+    };
+}
+// The emission decision every entry source shares — list items, table rows,
+// and the paragraph/blockquote sources to come: an own GitHub link that
+// resolved makes an item; a dead own link drops the entry and lifts its
+// children to the nearest live parent; no own link with children makes a
+// group — never a `repo_info`, that's the identity-borrowing bug; no own link
+// and no children is a non-GitHub leaf, kept in markdown, dropped from JSON.
+// TODO(future): preserve non-GitHub leaves in a separate shape.
+function emitEntryNodes(githubUrl, repoInfo, text, childrenJson) {
+    if (githubUrl && repoInfo) {
+        return [
+            {
+                node_type: 'item',
+                title: text.title,
+                description: text.description || null,
+                children: childrenJson,
+                repo_info: toRepoInfo(repoInfo),
+            },
+        ];
+    }
+    if (githubUrl) {
+        return childrenJson;
+    }
+    if (childrenJson.length > 0) {
+        return [
+            {
+                node_type: 'group',
+                title: text.title,
+                description: text.description || null,
+                children: childrenJson,
+            },
+        ];
+    }
+    return [];
+}
+function processListRecursively(listNode, repoInfoMap, sortOptions, isNested = false, 
+// 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) {
+    if (!isNested) {
+        const gateOpen = sectionGateOpen ??
+            countLinkedItems(listNode) >= sortOptions.minLinks;
+        if (!gateOpen) {
+            return [];
+        }
     }
     // Zip each item with its emitted JSON nodes and repo info so one sort orders
     // both the rendered AST and the emitted JSON. `emitted` is empty for
@@ -289,59 +485,31 @@ function processListRecursively(listNode, repoInfoMap, sortOptions, isNested = f
     // AST, dropped from JSON.
     const entries = [];
     for (const itemNode of listNode.children) {
-        const githubUrl = findOwnGitHubLink(itemNode);
+        const ownLink = findOwnGitHubLink(itemNode);
+        const githubUrl = ownLink?.url;
         const repoInfo = githubUrl ? (repoInfoMap.get(githubUrl) ?? null) : null;
-        const nestedLists = itemNode.children.filter((child) => child.type === 'list');
-        const childrenJson = nestedLists.flatMap(nestedList => processListRecursively(nestedList, repoInfoMap, sortOptions, true));
-        let title = '';
-        let description = '';
-        const paragraph = itemNode.children.find(p => p.type === 'paragraph');
-        if (paragraph) {
-            const linkIndex = paragraph.children.findIndex((c) => c.type === 'link');
-            if (linkIndex !== -1) {
-                // Title = leading text + the first link's text, so prefix tags like
-                // "[UPDATED]" survive; description is the prose trailing the link.
-                title = getInlineText(paragraph.children.slice(0, linkIndex + 1));
-                description = stripLeadingNoise(getInlineText(paragraph.children.slice(linkIndex + 1)));
-            }
-            else {
-                // No link: the whole paragraph is the title, so leave description empty
-                // (avoid echoing the title back).
-                title = getInlineText(paragraph.children);
-                description = '';
-            }
-        }
-        // No-own-link items with children become groups — NEVER give them a
-        // `repo_info`, that's the identity-borrowing bug. No-own-link, no-child
-        // items are non-GitHub leaves: kept in markdown, dropped from JSON.
-        // TODO(future): preserve non-GitHub leaves in a separate shape.
-        let emitted = [];
-        if (githubUrl && repoInfo) {
-            emitted = [
-                {
-                    node_type: 'item',
-                    title,
-                    description: description || null,
-                    children: childrenJson,
-                    repo_info: toRepoInfo(repoInfo),
-                },
-            ];
-        }
-        else if (githubUrl) {
-            // Dead target: the item itself is not emitted; its children lift to this
-            // list's level — the nearest live parent.
-            emitted = childrenJson;
-        }
-        else if (childrenJson.length > 0) {
-            emitted = [
-                {
-                    node_type: 'group',
-                    title,
-                    description: description || null,
-                    children: childrenJson,
-                },
-            ];
+        // Nested content is the item's children: deeper lists as before, plus
+        // tables — the AnimeResearch shape wraps a <details><summary> block and
+        // its table inside one list item. Both emit under the parent item
+        // regardless of the gate: the top-level call already gated the section.
+        const nestedContent = itemNode.children.filter((child) => child.type === 'list' || child.type === 'table');
+        const childrenJson = nestedContent.flatMap(child => child.type === 'list'
+            ? processListRecursively(child, repoInfoMap, sortOptions, true)
+            : processTableRows(child, repoInfoMap, true));
+        // 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.
+        const paragraph = itemNode.children.find((child) => child.type === 'paragraph');
+        const entryText = splitEntryText(paragraph?.children ?? []);
+        // A details-wrapped item carries its visible text in the summary, not in
+        // a paragraph — that text is the group's title.
+        if (!entryText.title) {
+            entryText.title = listItemSummaryTitle(itemNode);
         }
+        // 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);
+        const emitted = emitEntryNodes(githubUrl, repoInfo, entryText, childrenJson);
         entries.push({ emitted, node: itemNode, repoInfo });
     }
     if (sortOptions.by) {
@@ -351,6 +519,244 @@ function processListRecursively(listNode, repoInfoMap, sortOptions, isNested = f
     listNode.children = entries.map(entry => entry.node);
     return entries.flatMap(entry => entry.emitted);
 }
+// Title with the fallbacks every entry source shares when the split yields no
+// text (e.g. an image-only card link): the own link's text, then the repo
+// name.
+function entryTitle(base, ownLink, repoInfo) {
+    return (base ||
+        (ownLink ? getInlineText(ownLink.children) : '') ||
+        repoInfo?.repo ||
+        '');
+}
+// Table rows are entries under the nearest open container. The common shape —
+// scala's `[name](repo) | description`, spec tables with the link in a later
+// column — holds ONE repo per row: the title is the first cell's text (the
+// own link's text, then the repo name, when the first cell is empty), the
+// description the remaining cells' text (badge images carry no text nodes, so
+// they never pollute it). Card grids pin several repos per row, each cell its
+// own card, so those emit one entry per link-bearing cell. A linked row above
+// the delimiter is content like any other (grid tables have no label header;
+// pure-label header rows carry no links and emit nothing). Rows stay in source
+// order — unlike the unranked lists the product sorts, a table's row order is
+// part of its meaning.
+function processTableRows(tableNode, repoInfoMap, gateOpen) {
+    if (!gateOpen) {
+        return [];
+    }
+    const items = [];
+    for (const row of tableNode.children) {
+        if (row.type !== 'tableRow') {
+            continue;
+        }
+        const cellLinks = row.children.map(cell => findFirstGitHubLink(cell));
+        const distinctUrls = new Set(cellLinks.flatMap(link => (link ? [link.url] : [])));
+        if (distinctUrls.size === 0) {
+            continue;
+        }
+        if (distinctUrls.size === 1) {
+            const ownLink = cellLinks.find((link) => !!link);
+            if (!ownLink) {
+                continue;
+            }
+            const repoInfo = repoInfoMap.get(ownLink.url) ?? null;
+            const firstCellText = splitEntryText(row.children[0]?.children ?? []);
+            const restCellsText = row.children
+                .slice(1)
+                .map(cell => getNodeText(cell))
+                .filter(Boolean);
+            items.push(...emitEntryNodes(ownLink.url, repoInfo, {
+                title: entryTitle(firstCellText.title, ownLink, repoInfo),
+                description: [firstCellText.description, ...restCellsText]
+                    .join(' ')
+                    .trim(),
+            }, []));
+            continue;
+        }
+        const emittedUrls = new Set();
+        for (const [cellIndex, ownLink] of cellLinks.entries()) {
+            if (!ownLink || emittedUrls.has(ownLink.url)) {
+                continue;
+            }
+            emittedUrls.add(ownLink.url);
+            const repoInfo = repoInfoMap.get(ownLink.url) ?? null;
+            const cellText = splitEntryText(row.children[cellIndex].children);
+            items.push(...emitEntryNodes(ownLink.url, repoInfo, {
+                title: entryTitle(cellText.title, ownLink, repoInfo),
+                description: cellText.description,
+            }, []));
+        }
+    }
+    return items;
+}
+// A top-level paragraph can BE an entry, not only feed container prose. Two
+// corpus families qualify (progress/empty-tree-parses.md, step 4): a GitHub
+// link LEADING the paragraph behind a short entry label, or the paragraph
+// ending in a tag cluster whose GitHub link carries the identity — the
+// paper-list shape whose first link points at the paper and a [Code]/[Github]
+// tag at the end, name/author lines ending in that tag, and dated lines
+// ("… [Github] 4 Feb 2023"). Prose that mentions a repo ("Please see
+// CONTRIBUTING", "See also [repo]", intro text ending in a bare repo URL) is
+// neither and stays description. Calibrated on the 2,293-README corpus plus
+// the fixture fleet, not intuition: an entry label is a TAG (empty, CJK/emoji,
+// bracketed, or colon-terminated) — never bare English prose — and the
+// identity link must carry text, so the ubiquitous image-only awesome badge
+// is not an entry.
+const ENTRY_LABEL_MAX = 15;
+const ENTRY_TRAILING_MAX = 3;
+const TAG_LINK_TEXT = /^[\[\]()*\s:_-]*(?:source\s+code|code|github|repo|source|src|project|paper|page|web|site|home|official|notebook|demo|data|docs|implementation|arxiv)\b[\[\]()*\s:_-]*$/i;
+const URL_LINK_TEXT = /^https?:\/\/\S+$/i;
+// 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.
+const DATE_TRAILING = /^(\d{1,2}[ -])?([a-zà-ÿ]{3,12}[ -])?\d{2,4}$/i;
+// Boilerplate navigation line present in most mirror READMEs; casing and
+// the optional "the" vary ("⬆ back to top", "⬆️ Back to Top",
+// "Back to the Top").
+const BACK_TO_TOP = /back to (?:the )?top/i;
+// Tag-shaped leading label: empty, non-ASCII (CJK labels like 项目地址：,
+// emoji markers), bracketed ([6] Diffusion:), or colon-terminated (Demo:).
+// English prose ("Please see", "See also", "Inspired by the") is none of
+// these — those are cross-reference sentences, not entry labels.
+function isEntryLabel(label) {
+    return (label === '' ||
+        /[^\x00-\x7f]/.test(label) ||
+        label.startsWith('[') ||
+        /[:：]$/.test(label));
+}
+// Flattened view of a paragraph's (or heading's) inline content for the entry
+// test: the first link, the free text before it, and the free text after the
+// link cluster (emphasis recursed into; link labels, images, and inline html
+// carry no positional weight — a bare [Code] tag's label is not trailing
+// prose).
+function scanInlines(paragraph) {
+    let firstLink;
+    let label = '';
+    let trailing = '';
+    const walk = (node) => {
+        if (node.type === 'link') {
+            if (firstLink) {
+                trailing = '';
+            }
+            firstLink = firstLink ?? node;
+            return;
+        }
+        if (node.type === 'text') {
+            if (firstLink) {
+                trailing += node.value;
+            }
+            else {
+                label += node.value;
+            }
+            return;
+        }
+        for (const child of node.children ?? []) {
+            walk(child);
+        }
+    };
+    for (const child of paragraph.children) {
+        walk(child);
+    }
+    return { firstLink, label: label.trim(), trailing: trailing.trim() };
+}
+// True when nothing of substance follows the paragraph's last link: pure
+// punctuation, or a date (see DATE_TRAILING).
+function tagClusterEndsParagraph(trailing) {
+    if (trailing.length <= ENTRY_TRAILING_MAX) {
+        return true;
+    }
+    return DATE_TRAILING.test(trailing.replace(/^[\[\]()*\s:;,_-]+/, ''));
+}
+// The GitHub link that makes a top-level paragraph — or a heading inside a
+// blockquote — an entry, if it is one (see the family comment above). Null
+// for plain prose.
+function paragraphEntryLink(paragraph) {
+    const githubLink = findFirstGitHubLink(paragraph);
+    if (!githubLink) {
+        return undefined;
+    }
+    const labelText = getInlineText(githubLink.children);
+    if (!labelText) {
+        return undefined;
+    }
+    const scan = scanInlines(paragraph);
+    if (scan.firstLink === githubLink &&
+        scan.label.length <= ENTRY_LABEL_MAX &&
+        isEntryLabel(scan.label)) {
+        return githubLink;
+    }
+    if (tagClusterEndsParagraph(scan.trailing) &&
+        (TAG_LINK_TEXT.test(labelText) ||
+            (URL_LINK_TEXT.test(labelText) && scan.firstLink !== githubLink))) {
+        return githubLink;
+    }
+    return undefined;
+}
+function blockquoteEntries(blockquote) {
+    const faces = [];
+    let sawParagraph = false;
+    for (const child of blockquote.children) {
+        if (child.type === 'paragraph') {
+            if (sawParagraph) {
+                continue;
+            }
+            sawParagraph = true;
+            const link = paragraphEntryLink(child);
+            if (link) {
+                faces.push({ inlines: child.children, link });
+            }
+        }
+        else if (child.type === 'heading') {
+            const link = paragraphEntryLink(child);
+            if (link) {
+                faces.push({ inlines: child.children, link });
+            }
+        }
+    }
+    return faces;
+}
+// The shared entry emission for the non-list sources (paragraph entries,
+// blockquote cards): resolve, split, title-fallback — the same decisions the
+// list and table paths make through the same helpers.
+function entryNodesFor(ownLink, inlines, repoInfoMap) {
+    const repoInfo = repoInfoMap.get(ownLink.url) ?? null;
+    const entryText = splitEntryText(inlines);
+    return emitEntryNodes(ownLink.url, repoInfo, {
+        title: entryTitle(entryText.title, ownLink, repoInfo),
+        description: entryText.description,
+    }, []);
+}
+// The <details><summary>…</summary> collapsible-section idiom: the summary
+// text delimits structure like a heading would (java's generated README,
+// paper-list tables behind "1.1 <topic>" summaries). kbd chips inside the
+// summary ("5 projects") are metadata, not the title. A details block with
+// 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) {
+    const match = DETAILS_SUMMARY.exec(htmlValue);
+    if (!match) {
+        return null;
+    }
+    const title = match[1]
+        .replace(/<kbd>[\s\S]*?<\/kbd>/gi, '')
+        .replace(/<[^>]+>/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+    return title || null;
+}
+// The summary text of a <details><summary> block inside a list item, when the
+// item has no paragraph text of its own.
+function listItemSummaryTitle(itemNode) {
+    for (const child of itemNode.children) {
+        if (child.type === 'html') {
+            const title = detailsSummaryTitle(child.value);
+            if (title) {
+                return title;
+            }
+        }
+    }
+    return '';
+}
 const INVALID_TITLE_PATTERNS = [
     /^contributing/i,
     /^license$/i,
@@ -403,7 +809,7 @@ const TOC_TITLE_PATTERNS = [/^contents$/i, /^table of contents$/i];
 // A heading that delimits content structure. Text-less headings (a bare `#`,
 // an image-only heading) are spacers in real docs; TOC headings are structure
 // mirrors. Neither participates in the section tree.
-function isStructuralHeading(node) {
+export function isStructuralHeading(node) {
     const title = getNodeText(node);
     return (!!title && !TOC_TITLE_PATTERNS.some(pattern => pattern.test(title.trim())));
 }
@@ -424,6 +830,17 @@ function findTitleHeadingIndex(tree) {
         node.depth === 1 &&
         isValidTitle(getNodeText(node)));
 }
+// The heading branding owns even when it isn't a *valid* title: a generic
+// first H1 ("# Guides", "# Contents") is still the de-facto title slot —
+// applyBrandingToTree replaces it — so the section tree must not treat it
+// as a section wrapping the whole document.
+export function findTitleSlotIndex(tree) {
+    const titleHeadingIndex = findTitleHeadingIndex(tree);
+    if (titleHeadingIndex !== -1) {
+        return titleHeadingIndex;
+    }
+    return tree.children.findIndex((node) => node.type === 'heading' && node.depth === 1);
+}
 /**
  * Makes the rendered H1 match metadata.title, replacing whichever heading
  * occupies the title slot (a valid title H1, else the first generic H1, else a
@@ -460,13 +877,7 @@ function processTree(tree, repoInfoMap, sortOptions, originalRepository) {
     let documentTitle = titleHeadingIndex === -1
         ? ''
         : getNodeText(tree.children[titleHeadingIndex]);
-    // The heading branding owns even when it isn't a *valid* title: a generic
-    // first H1 ("# Guides", "# Contents") is still the de-facto title slot —
-    // applyBrandingToTree replaces it — so the section tree must not treat it
-    // as a section wrapping the whole document.
-    const titleSlotIndex = titleHeadingIndex !== -1
-        ? titleHeadingIndex
-        : tree.children.findIndex((node) => node.type === 'heading' && node.depth === 1);
+    const titleSlotIndex = findTitleSlotIndex(tree);
     // Derive a subject from the *source* repository name when no valid H1 is
     // present. Using the source — not the enhanced/mirror repo — keeps the org
     // name out of the title.
@@ -477,8 +888,34 @@ function processTree(tree, repoInfoMap, sortOptions, originalRepository) {
         }
     }
     const sectionDepth = findSectionDepth(tree, titleSlotIndex);
-    const sections = [];
+    const gateForSection = sectionGatePasses(tree, titleSlotIndex, sectionDepth, repoInfoMap, sortOptions);
+    // Sections finalize out of document order when a details-section closes
+    // inside its parent section's span, so each carries the document index it
+    // opened at for the document-order sort at the end.
+    const sectionRecords = [];
     const stack = [];
+    // Entry emission shared by the paragraph and blockquote-card faces: the
+    // implicit section opens for a containerless entry (the stack-bottom
+    // invariant), the minLinks gate is the section aggregate, and a gated or
+    // dead entry emits nothing and stays out of the description (mirrors dead
+    // list items).
+    const emitStandaloneEntry = (ownLink, inlines, atIndex) => {
+        if (stack.length === 0) {
+            openImplicitSection(stack, atIndex);
+        }
+        if (gateForSection(stack[0])) {
+            stack[stack.length - 1].children.push(...entryNodesFor(ownLink, inlines, repoInfoMap));
+        }
+    };
+    // A standalone entry restating the repo of an open item container (crypto's
+    // generated cards repeat the repo URL in a line under the link-heading) is
+    // that item's description, not a second item for the same repo. The
+    // repoInfoMap resolves both URLs through one per-repo memo, so identity
+    // comparison holds even for aliased spellings.
+    const rementionsOpenItem = (link) => {
+        const repoInfo = repoInfoMap.get(link.url);
+        return !!repoInfo && stack.some(container => container.repoInfo === repoInfo);
+    };
     for (let i = 0; i < tree.children.length; i++) {
         const node = tree.children[i];
         if (node.type === 'heading') {
@@ -488,32 +925,117 @@ function processTree(tree, repoInfoMap, sortOptions, originalRepository) {
             if (i === titleSlotIndex || !isStructuralHeading(node)) {
                 continue;
             }
-            closeContainers(stack, node.depth, sections);
-            openContainer(stack, node, sectionDepth, repoInfoMap);
+            const headingEntry = entryHeadingInfo(node, repoInfoMap);
+            // The promotion flavor of the entry test: a textless identity link is
+            // a title-line badge, not an entry (see entryHeadingInfo).
+            const promotedEntry = headingEntry && getInlineText(headingEntry.link.children)
+                ? headingEntry
+                : null;
+            closeContainers(stack, node.depth, sectionRecords, !!promotedEntry);
+            openContainer(stack, node, i, sectionDepth, promotedEntry, headingEntry);
+        }
+        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);
+            // 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.
+            if (ownLink && !rementionsOpenItem(ownLink)) {
+                emitStandaloneEntry(ownLink, node.children, i);
+            }
+            else {
+                const container = stack[stack.length - 1];
+                // Avoid adding boilerplate "back to top" links to descriptions.
+                if (container && text && !BACK_TO_TOP.test(text)) {
+                    container.description = container.description
+                        ? `${container.description}\n${text}`
+                        : text;
+                }
+            }
         }
-        else if (node.type === 'paragraph' || node.type === 'blockquote') {
+        else if (node.type === 'blockquote') {
             const text = getNodeText(node);
-            const container = stack[stack.length - 1];
-            // Avoid adding boilerplate "back to top" links to descriptions.
-            if (container && text && !text.includes('back to top')) {
-                container.description = container.description
-                    ? `${container.description}\n${text}`
-                    : text;
+            // A card blockquote is the blockquote face of entries — one per
+            // qualifying paragraph/heading child; any other quote is container
+            // prose.
+            const faces = BACK_TO_TOP.test(text)
+                ? []
+                : blockquoteEntries(node).filter(face => !rementionsOpenItem(face.link));
+            if (faces.length > 0) {
+                for (const face of faces) {
+                    emitStandaloneEntry(face.link, face.inlines, i);
+                }
+            }
+            else {
+                const container = stack[stack.length - 1];
+                // Avoid adding boilerplate "back to top" links to descriptions.
+                if (container && text && !BACK_TO_TOP.test(text)) {
+                    container.description = container.description
+                        ? `${container.description}\n${text}`
+                        : text;
+                }
+            }
+        }
+        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) {
+                closeInnermostDetails(stack, sectionRecords);
+                // 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.
+                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,
+                });
+            }
+            else if (DETAILS_CLOSE.test(node.value)) {
+                closeInnermostDetails(stack, sectionRecords);
             }
         }
         else if (node.type === 'list') {
+            // A list with no open container still means content: synthesize the
+            // implicit section for it (see openImplicitSection). Afterwards the
+            // stack bottom is always a section — implicit or real — which is the
+            // invariant the gate below and closeContainers rely on.
+            if (stack.length === 0) {
+                openImplicitSection(stack, i);
+            }
             // Every list inside the open container contributes items — a section is
-            // not closed by its first list. With no open container (preamble), the
-            // list is not part of any JSON section, but its AST is still sorted so
-            // the rendered markdown matches.
-            const items = processListRecursively(node, repoInfoMap, sortOptions);
-            const container = stack[stack.length - 1];
-            if (container) {
-                container.children.push(...items);
+            // 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, false, gateForSection(stack[0]));
+            stack[stack.length - 1].children.push(...items);
+        }
+        else if (node.type === 'table') {
+            // Tables hold entries the same way lists do — the implicit section opens
+            // for one with no open container (the stack-bottom invariant), and the
+            // minLinks gate is the same section aggregate.
+            if (stack.length === 0) {
+                openImplicitSection(stack, i);
             }
+            const items = processTableRows(node, repoInfoMap, gateForSection(stack[0]));
+            stack[stack.length - 1].children.push(...items);
         }
     }
-    closeContainers(stack, 0, sections);
+    closeContainers(stack, 0, sectionRecords);
+    const sections = sectionRecords
+        .sort((a, b) => a.headingIndex - b.headingIndex)
+        .map(record => record.section);
     return { sections, title: documentTitle, titleHeadingIndex };
 }
 // The heading depth that opens top-level sections: the shallowest structural
@@ -533,87 +1055,308 @@ function findSectionDepth(tree, titleSlotIndex) {
     });
     return depth;
 }
-// A heading whose only link is a live GitHub link represents a resource, not a
-// container — the link-heading pattern (`#### [Repo](github…)`). Badge images
-// wrapped in links or multiple links disqualify (more than one link means the
-// heading is not "the" resource), as does a dead target.
-function soleLiveHeadingLink(heading, repoInfoMap) {
-    const links = heading.children.filter((child) => child.type === 'link');
-    if (links.length !== 1) {
+function entryHeadingInfo(heading, repoInfoMap) {
+    const link = findFirstGitHubLink(heading);
+    if (!link) {
         return null;
     }
-    return repoInfoMap.get(links[0].url) ?? null;
+    const repoInfo = repoInfoMap.get(link.url);
+    return repoInfo ? { link, repoInfo } : null;
 }
-function openContainer(stack, heading, sectionDepth, repoInfoMap) {
+function openContainer(stack, heading, headingIndex, sectionDepth, promotedEntry, headingEntry) {
     const title = getNodeText(heading);
     // Sections sit at the section level — and any heading met with an empty
     // stack is promoted: a deeper heading before the first section (orphan
-    // subheading) still owns its subtree, and a link-heading at section level
-    // becomes a section rather than a top-level item, which the contract has no
-    // place for.
+    // subheading) still owns its subtree. A promoted ENTRY heading (see
+    // entryHeadingInfo) is an item, not a section: the JSON contract has no
+    // top-level items, so a synthesized section wraps the whole run of them.
     if (stack.length === 0 || heading.depth === sectionDepth) {
+        if (promotedEntry) {
+            if (stack.length === 0) {
+                openSynthesizedSection(stack, headingIndex, sectionDepth);
+            }
+            stack.push({
+                children: [],
+                description: '',
+                headingDepth: heading.depth,
+                headingIndex,
+                kind: 'item',
+                repoInfo: promotedEntry.repoInfo,
+                title,
+            });
+            return;
+        }
         stack.push({
             children: [],
             description: '',
             headingDepth: heading.depth,
+            headingIndex,
             kind: 'section',
             title,
         });
         return;
     }
-    const repoInfo = soleLiveHeadingLink(heading, repoInfoMap);
+    // A deeper entry heading opens an item container the same way a promoted
+    // one does — children and prose below it collect as its content.
     stack.push({
         children: [],
         description: '',
         headingDepth: heading.depth,
-        kind: repoInfo ? 'item' : 'group',
-        repoInfo: repoInfo ?? undefined,
+        headingIndex,
+        kind: headingEntry ? 'item' : 'group',
+        repoInfo: headingEntry?.repoInfo,
         title,
     });
 }
-// Finalize every container a heading of `depth` closes (same-or-shallower),
-// bottom-up so each finalized node lands in its parent. Pruning falls out of
-// the finalize rule: a section/group whose children array is empty (no items
-// anywhere beneath — lists only return item-bearing nodes, and empty children
-// were never appended) is dropped; an item always survives, it IS the content.
-// The stack bottom is always a section (openContainer's promotion guarantees
-// it), so a finalized group/item always has a parent to land in.
-function closeContainers(stack, depth, sections) {
-    while (stack.length > 0 &&
-        stack[stack.length - 1].headingDepth >= depth) {
-        const container = stack.pop();
-        if (container.children.length === 0 && container.kind !== 'item') {
-            continue;
+// A document can hold registry content with no heading above it — headingless
+// docs, TOC-only docs, or preamble entries (list, table) before the first
+// section heading. Rather than dropping them, the first one synthesizes the
+// section it implicitly belongs to ("Overview"). It behaves exactly like a
+// real section:
+// closed by the first structural heading (or document end), gated with its
+// whole subtree, and pruned when empty.
+function openImplicitSection(stack, atIndex) {
+    stack.push({
+        children: [],
+        description: '',
+        // Infinity so ANY structural heading closes it in closeContainers and
+        // ends its span in the section gate — the implicit section never reaches
+        // past the preamble.
+        headingDepth: Infinity,
+        // One before the opening list so the gate's scan (from headingIndex + 1)
+        // counts that list itself.
+        headingIndex: atIndex - 1,
+        kind: 'section',
+        title: 'Overview',
+    });
+}
+// The section synthesized around a run of promoted entry headings
+// (openContainer's entry branch). It behaves like the implicit section — same
+// "Overview" title, gated by its subtree — but sits at sectionDepth, so the
+// first plain heading at that level ends the run, and closeContainers'
+// stopAtSynthesized keeps the entry headings' own pops from closing it:
+// consecutive entry headings are siblings INSIDE it.
+function openSynthesizedSection(stack, firstEntryIndex, depth) {
+    stack.push({
+        children: [],
+        description: '',
+        headingDepth: depth,
+        // One before the first entry heading so the gate's scan (from
+        // headingIndex + 1) counts that heading itself.
+        headingIndex: firstEntryIndex - 1,
+        kind: 'section',
+        openedBySynthesis: true,
+        title: 'Overview',
+    });
+}
+// The minLinks gate scoped to a SECTION: every entry source in the section
+// counts together (list items, table rows, entry paragraphs, entry headings,
+// blockquote faces) — best-of-style documents put each entry in its own
+// single-item list, which the per-list gate dropped one by one. The section's
+// subtree runs from its heading to the first structural heading at or above
+// its depth (the same heading that would close it in closeContainers).
+//
+// Heading-per-entry documents (FBI-tools' `### name` + link paragraph, FLOSS's
+// `## game` + link cluster) put exactly ONE entry in each section, so every
+// section fails the gate alone and the whole document drops. They are not
+// sparse sections but flat entry lists delimited by headings: a section at
+// sectionDepth that fails alone is re-gated against its RUN — the maximal
+// sequence of adjacent section spans each holding at most one entry. The
+// noise floor survives: a single one-entry section between multi-entry
+// sections is a run of one and stays dropped.
+function sectionGatePasses(tree, titleSlotIndex, sectionDepth, repoInfoMap, sortOptions) {
+    const cache = new Map();
+    // Linked entries from scanStart to the first structural heading that would
+    // close a container of closeDepth. An entry heading counts as an entry
+    // wherever it sits inside the span — it opens an item, not a container —
+    // except at the scanned section's own depth, where the walk closes that
+    // section when the entry run starts (a same-depth entry heading is content
+    // only for the synthesized wrapper, hence sameDepthEntriesAreContent).
+    const scanCount = (scanStart, closeDepth, sameDepthEntriesAreContent) => {
+        let linkedEntries = 0;
+        for (let j = scanStart; j < tree.children.length; j++) {
+            const node = tree.children[j];
+            if (node.type === 'heading') {
+                if (j === titleSlotIndex || !isStructuralHeading(node)) {
+                    continue;
+                }
+                if (entryHeadingInfo(node, repoInfoMap)) {
+                    if (sameDepthEntriesAreContent || node.depth > closeDepth) {
+                        linkedEntries += 1;
+                    }
+                    else {
+                        break;
+                    }
+                    continue;
+                }
+                if (node.depth <= closeDepth) {
+                    break;
+                }
+                continue;
+            }
+            if (node.type === 'list') {
+                linkedEntries += countLinkedItems(node);
+            }
+            else if (node.type === 'table') {
+                linkedEntries += countLinkedRows(node);
+            }
+            else if (node.type === 'paragraph' && paragraphEntryLink(node)) {
+                linkedEntries += 1;
+            }
+            else if (node.type === 'blockquote') {
+                linkedEntries += blockquoteEntries(node).length;
+            }
         }
-        const description = container.description || null;
-        if (container.kind === 'section') {
-            sections.push({
-                description,
-                items: container.children,
-                title: container.title,
-            });
-            continue;
+        return linkedEntries;
+    };
+    // A boundary's entry count for the run walk: the heading itself when it is
+    // an entry heading, plus its span's entries (the span closes at the first
+    // heading at or above the boundary's OWN depth, exactly where the walk
+    // closes that section).
+    const spanCountCache = new Map();
+    const spanCount = (boundaryIndex) => {
+        const cached = spanCountCache.get(boundaryIndex);
+        if (cached !== undefined) {
+            return cached;
         }
-        const parent = stack[stack.length - 1];
-        // Non-section containers always have an open parent (stack invariant), and
-        // kind === 'item' exactly when repoInfo is set.
-        if (container.repoInfo) {
-            parent.children.push({
-                children: container.children,
-                description,
-                node_type: 'item',
-                repo_info: toRepoInfo(container.repoInfo),
-                title: container.title,
+        const heading = tree.children[boundaryIndex];
+        const count = (entryHeadingInfo(heading, repoInfoMap) ? 1 : 0) +
+            scanCount(boundaryIndex + 1, heading.depth, false);
+        spanCountCache.set(boundaryIndex, count);
+        return count;
+    };
+    // The section boundaries in document order, by the walk's own promotion
+    // rule (openContainer): a heading opens a section when it sits at
+    // sectionDepth or arrives with nothing open — FLOSS-style documents have a
+    // lone late H1 that pins sectionDepth at 1 while every `## game` heading
+    // alternately closes its predecessor (stack empties) and is promoted. The
+    // depth simulation mirrors closeContainers/openContainer exactly.
+    let boundaries;
+    const sectionBoundaries = () => {
+        if (!boundaries) {
+            const indices = [];
+            const openDepths = [];
+            tree.children.forEach((node, i) => {
+                if (node.type !== 'heading' || i === titleSlotIndex) {
+                    return;
+                }
+                if (!isStructuralHeading(node)) {
+                    return;
+                }
+                while (openDepths.length > 0 &&
+                    openDepths[openDepths.length - 1] >= node.depth) {
+                    openDepths.pop();
+                }
+                if (openDepths.length === 0 || node.depth === sectionDepth) {
+                    indices.push(i);
+                }
+                openDepths.push(node.depth);
             });
+            boundaries = indices;
         }
-        else {
-            parent.children.push({
-                children: container.children,
-                description,
-                node_type: 'group',
-                title: container.title,
-            });
+        return boundaries;
+    };
+    const runTotal = (section) => {
+        const list = sectionBoundaries();
+        const k = list.indexOf(section.headingIndex);
+        if (k === -1) {
+            return spanCount(section.headingIndex);
         }
+        let total = spanCount(section.headingIndex);
+        for (const direction of [-1, 1]) {
+            for (let m = k + direction; m >= 0 && m < list.length; m += direction) {
+                const count = spanCount(list[m]);
+                if (count > 1) {
+                    break;
+                }
+                total += count;
+            }
+        }
+        return total;
+    };
+    return section => {
+        const cached = cache.get(section.headingIndex);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const own = scanCount(section.headingIndex + 1, section.headingDepth, !!section.openedBySynthesis);
+        const passes = own >= sortOptions.minLinks ||
+            (!section.openedBySynthesis &&
+                sectionBoundaries().includes(section.headingIndex) &&
+                runTotal(section) >= sortOptions.minLinks);
+        cache.set(section.headingIndex, passes);
+        return passes;
+    };
+}
+// Prune-or-emit one popped container: a section/group whose children array is
+// empty (no items anywhere beneath — the entry sources only return
+// item-bearing nodes) is dropped; an item always survives, it IS the content.
+// Non-section containers always have an open parent (stack invariant), and
+// kind === 'item' exactly when repoInfo is set.
+function finalizeContainer(container, stack, sectionRecords) {
+    if (container.children.length === 0 && container.kind !== 'item') {
+        return;
+    }
+    const description = container.description || null;
+    if (container.kind === 'section') {
+        sectionRecords.push({
+            headingIndex: container.headingIndex,
+            section: { description, items: container.children, title: container.title },
+        });
+        return;
+    }
+    const parent = stack[stack.length - 1];
+    if (container.repoInfo) {
+        parent.children.push({
+            children: container.children,
+            description,
+            node_type: 'item',
+            repo_info: toRepoInfo(container.repoInfo),
+            title: container.title,
+        });
+    }
+    else {
+        parent.children.push({
+            children: container.children,
+            description,
+            node_type: 'group',
+            title: container.title,
+        });
+    }
+}
+// Finalize every container a heading of `depth` closes (same-or-shallower),
+// bottom-up so each finalized node lands in its parent. The stack bottom is
+// always a section (openContainer's promotion guarantees it), so a finalized
+// group/item always has a parent to land in. stopAtSynthesized: the pop an
+// 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, stopAtSynthesized = false) {
+    while (stack.length > 0 &&
+        stack[stack.length - 1].headingDepth >= depth) {
+        if (stopAtSynthesized && stack[stack.length - 1].openedBySynthesis) {
+            break;
+        }
+        finalizeContainer(stack.pop(), stack, sectionRecords);
+    }
+}
+// Ends the innermost open details-section and everything opened inside it,
+// leaving the enclosing containers untouched — unlike a heading close, a
+// details boundary never ends its parent section, so content after the
+// collapsible block keeps collecting under it. A stray </details> (no
+// details-section open) is a no-op.
+function closeInnermostDetails(stack, sectionRecords) {
+    let detailsIndex = -1;
+    for (let s = stack.length - 1; s >= 0; s--) {
+        if (stack[s].openedByDetails) {
+            detailsIndex = s;
+            break;
+        }
+    }
+    if (detailsIndex === -1) {
+        return;
+    }
+    while (stack.length > detailsIndex) {
+        finalizeContainer(stack.pop(), stack, sectionRecords);
     }
 }
 function serializeAst(tree, originalContent) {

package/dist/orchestrator.d.ts

@@ -9,6 +9,7 @@ export interface EnhanceOptions {
     log?: Logger;
     now?: Date;
     originalRepository: string;
+    originalRepositoryId?: number;
     originalRepositorySha?: string;
     relativeLinkPrefix?: string;
     /** Text substitutions applied to the source before it is parsed. */

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(), originalRepository, originalRepositorySha, relativeLinkPrefix = '', replacements = [], sortBy = '', enhancedRepository, enhancedRepositoryDescription, token, } = options;
+    const { content, disableBranding = false, log, now = new Date(), originalRepository, originalRepositoryId, originalRepositorySha, relativeLinkPrefix = '', replacements = [], sortBy = '', 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, originalRepository, relativeLinkPrefix, enhancedRepository, enhancedRepositoryDescription, originalRepositorySha, now, log);
+    const { finalContent, jsonData } = await processMarkdownContent(content, token, rules, sortOptions, originalRepository, relativeLinkPrefix, enhancedRepository, enhancedRepositoryDescription, originalRepositorySha, originalRepositoryId, now, log);
     return {
         finalContent,
         jsonData,

package/package.json

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