@enhansome/core 1.7.1 → 1.8.1

package/dist/github.d.ts

@@ -8,6 +8,7 @@ export type GithubClient = InstanceType<typeof HardenedOctokit>;
 export interface RepoInfoDetails {
     archived: boolean;
     description: null | string;
+    id: number;
     language: null | string;
     open_issues_count: number;
     owner: string;
@@ -75,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

@@ -72,6 +72,7 @@ export async function getRepoInfo(octokit, owner, repo) {
     return {
         archived: data.archived,
         description: data.description ?? null,
+        id: data.id,
         language: data.language,
         open_issues_count: data.open_issues_count,
         owner: data.owner.login,
@@ -81,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

@@ -17,6 +17,7 @@ export interface SortOptions {
 }
 export interface RepoInfo {
     archived: boolean;
+    id: number;
     language: null | string;
     last_commit: null | string;
     owner: string;
@@ -29,7 +30,7 @@ export interface JsonItem {
     children: JsonNode[];
     description: null | string;
     node_type: 'item';
-    repo_info?: RepoInfo;
+    repo_info: RepoInfo;
     title: string;
 }
 export interface JsonGroup {
@@ -44,6 +45,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;
 }
@@ -52,7 +54,7 @@ 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;
 }>;

package/dist/markdown.js

@@ -10,6 +10,7 @@ import { consoleLog } from './logger.js';
 export function toRepoInfo(details) {
     return {
         archived: details.archived,
+        id: details.id,
         language: details.language,
         last_commit: details.pushed_at,
         owner: details.owner,
@@ -78,7 +79,7 @@ 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);
@@ -98,6 +99,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,
@@ -282,10 +284,10 @@ function processListRecursively(listNode, repoInfoMap, sortOptions, isNested = f
     if (!isNested && itemsWithGitHubLinks.length < sortOptions.minLinks) {
         return [];
     }
-    // Zip each item with its JSON node and repo info so one sort orders both the
-    // rendered AST and the emitted JSON. `json` is null only for non-GitHub
-    // leaves (no own link, no nested GitHub children): kept in the AST, dropped
-    // from JSON.
+    // 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
+    // non-GitHub leaves (no own link, no nested GitHub children): kept in the
+    // AST, dropped from JSON.
     const entries = [];
     for (const itemNode of listNode.children) {
         const githubUrl = findOwnGitHubLink(itemNode);
@@ -314,37 +316,41 @@ function processListRecursively(listNode, repoInfoMap, sortOptions, isNested = f
         // `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 jsonData = null;
-        if (githubUrl) {
-            const item = {
-                node_type: 'item',
-                title,
-                description: description || null,
-                children: childrenJson,
-            };
-            if (repoInfo) {
-                item.repo_info = toRepoInfo(repoInfo);
-            }
-            jsonData = item;
+        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) {
-            jsonData = {
-                node_type: 'group',
-                title,
-                description: description || null,
-                children: childrenJson,
-            };
+            emitted = [
+                {
+                    node_type: 'group',
+                    title,
+                    description: description || null,
+                    children: childrenJson,
+                },
+            ];
         }
-        entries.push({ json: jsonData, node: itemNode, repoInfo });
+        entries.push({ emitted, node: itemNode, repoInfo });
     }
     if (sortOptions.by) {
         entries.sort((a, b) => compareByRepoInfo(sortOptions.by, a.repoInfo, b.repoInfo));
     }
     // Reorder the AST to match the sort so rendered markdown and JSON agree.
     listNode.children = entries.map(entry => entry.node);
-    return entries
-        .map(entry => entry.json)
-        .filter((json) => json !== null);
+    return entries.flatMap(entry => entry.emitted);
 }
 const INVALID_TITLE_PATTERNS = [
     /^contributing/i,
@@ -389,6 +395,19 @@ function isValidTitle(title) {
     }
     return !INVALID_TITLE_PATTERNS.some(pattern => pattern.test(title.trim()));
 }
+// Headings that mirror structure rather than delimit it. Unlike
+// INVALID_TITLE_PATTERNS (a title-detection aid — "## Tools" is a perfectly
+// good content section), a TOC heading never owns content: the worst offender
+// is a `# Table of Contents` H1 that would otherwise wrap the whole document
+// as its "section".
+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) {
+    const title = getNodeText(node);
+    return (!!title && !TOC_TITLE_PATTERNS.some(pattern => pattern.test(title.trim())));
+}
 /** Never duplicates "Awesome": if the title already contains it, append the suffix verbatim; otherwise prefix first. */
 function brandTitle(title) {
     const trimmed = title.trim();
@@ -442,6 +461,13 @@ 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);
     // 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.
@@ -451,52 +477,146 @@ function processTree(tree, repoInfoMap, sortOptions, originalRepository) {
             documentTitle = formatRepoNameAsTitle(repoName);
         }
     }
+    const sectionDepth = findSectionDepth(tree, titleSlotIndex);
     const sections = [];
-    let currentSection = null;
-    for (const node of tree.children) {
-        if (node.type === 'heading' && node.depth > 1) {
-            if (currentSection) {
-                sections.push(currentSection);
+    const stack = [];
+    for (let i = 0; i < tree.children.length; i++) {
+        const node = tree.children[i];
+        if (node.type === 'heading') {
+            // The title-slot H1 belongs to branding/metadata; non-structural
+            // headings (see isStructuralHeading) delimit nothing. Neither
+            // participates in the section tree.
+            if (i === titleSlotIndex || !isStructuralHeading(node)) {
+                continue;
             }
-            currentSection = {
-                description: '',
-                items: [],
-                title: getNodeText(node),
-            };
+            closeContainers(stack, node.depth, sections);
+            openContainer(stack, node, sectionDepth, repoInfoMap);
         }
-        else if (currentSection) {
-            if (node.type === 'paragraph') {
-                const paragraphText = getNodeText(node);
-                // Avoid adding boilerplate "back to top" links to description
-                if (!paragraphText.includes('back to top')) {
-                    if (currentSection.description) {
-                        currentSection.description += `\n${paragraphText}`;
-                    }
-                    else {
-                        currentSection.description = paragraphText;
-                    }
-                }
-            }
-            else if (node.type === 'list') {
-                const items = processListRecursively(node, repoInfoMap, sortOptions);
-                if (items.length > 0) {
-                    currentSection.items = items;
-                    sections.push(currentSection);
-                }
-                currentSection = null;
+        else if (node.type === 'paragraph' || 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;
             }
         }
         else if (node.type === 'list') {
-            // No active section: not part of any JSON section, but still sort its AST
-            // so the rendered markdown matches.
-            processListRecursively(node, repoInfoMap, sortOptions);
+            // 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);
+            }
         }
     }
-    if (currentSection) {
-        sections.push(currentSection);
-    }
+    closeContainers(stack, 0, sections);
     return { sections, title: documentTitle, titleHeadingIndex };
 }
+// 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
+// drop all their items. Non-structural headings are skipped here too (same
+// rule as the walk). Infinity when there is no such heading (no sections).
+function findSectionDepth(tree, titleSlotIndex) {
+    let depth = Infinity;
+    tree.children.forEach((node, i) => {
+        if (node.type === 'heading' &&
+            i !== titleSlotIndex &&
+            isStructuralHeading(node) &&
+            node.depth < depth) {
+            depth = node.depth;
+        }
+    });
+    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) {
+        return null;
+    }
+    return repoInfoMap.get(links[0].url) ?? null;
+}
+function openContainer(stack, heading, sectionDepth, repoInfoMap) {
+    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.
+    if (stack.length === 0 || heading.depth === sectionDepth) {
+        stack.push({
+            children: [],
+            description: '',
+            headingDepth: heading.depth,
+            kind: 'section',
+            title,
+        });
+        return;
+    }
+    const repoInfo = soleLiveHeadingLink(heading, repoInfoMap);
+    stack.push({
+        children: [],
+        description: '',
+        headingDepth: heading.depth,
+        kind: repoInfo ? 'item' : 'group',
+        repoInfo: repoInfo ?? undefined,
+        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;
+        }
+        const description = container.description || null;
+        if (container.kind === 'section') {
+            sections.push({
+                description,
+                items: container.children,
+                title: container.title,
+            });
+            continue;
+        }
+        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,
+            });
+        }
+        else {
+            parent.children.push({
+                children: container.children,
+                description,
+                node_type: 'group',
+                title: container.title,
+            });
+        }
+    }
+}
 function serializeAst(tree, originalContent) {
     let finalContent = unified()
         .use(remarkStringify)

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.7.1",
+  "version": "1.8.1",
   "description": "Library core for enhansome — enhance markdown with GitHub star counts.",
   "repository": {
     "type": "git",