@enhansome/core 1.9.0 → 1.10.1

package/dist/github.d.ts

@@ -77,11 +77,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.
+ * The repo's full info, for the JSON metadata — the numeric id consumers key
+ * stable node ids on, plus the stars/language/last_commit the root's own
+ * metadata row is built from. Returns null (logged) instead of failing the
+ * run: metadata is 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 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>;
 /** 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

@@ -83,16 +83,17 @@ export async function getRepoInfo(octokit, owner, repo) {
     };
 }
 /**
- * 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.
+ * The repo's full info, for the JSON metadata — the numeric id consumers key
+ * stable node ids on, plus the stars/language/last_commit the root's own
+ * metadata row is built from. Returns null (logged) instead of failing the
+ * run: metadata is not a gate; consumers fall back when it is missing.
  */
-export async function getRepoId(octokit, owner, repo) {
+export async function getRepoInfoOrNull(octokit, owner, repo) {
     try {
-        return (await getRepoInfo(octokit, owner, repo)).id;
+        return await getRepoInfo(octokit, owner, repo);
     }
     catch (error) {
-        octokit.log.error(`Failed to fetch repo id for ${owner}/${repo}: ${formatRequestError(error)}`);
+        octokit.log.error(`Failed to fetch repo info for ${owner}/${repo}: ${formatRequestError(error)}`);
         return null;
     }
 }

package/dist/index.d.ts

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

package/dist/index.js

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

@@ -45,8 +45,7 @@ export interface JsonMetadata {
     enhanced_repository: null | string;
     enhanced_repository_description: null | string;
     last_updated: string;
-    original_repository: string;
-    original_repository_id: null | number;
+    original_repository_info: null | RepoInfo;
     original_repository_sha: null | string;
     title: string;
 }
@@ -55,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, originalRepositoryId?: number, now?: Date, log?: Logger): Promise<{
+export declare function processMarkdownContent(originalContent: string, token: string, replacements?: ReplacementRule[], sortOptions?: SortOptions, relativeLinkPrefix?: string, enhancedRepository?: string, enhancedRepositoryDescription?: string, originalRepositorySha?: string, originalRepositoryInfo?: null | RepoInfoDetails, now?: Date, log?: Logger): Promise<{
     finalContent: string;
     jsonData: JsonOutput;
 }>;

package/dist/markdown.js

@@ -79,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, originalRepositoryId, now = new Date(), log = consoleLog) {
+export async function processMarkdownContent(originalContent, token, replacements = [], sortOptions = { by: '', minLinks: 2 }, relativeLinkPrefix = '', enhancedRepository, enhancedRepositoryDescription, originalRepositorySha, originalRepositoryInfo, 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);
@@ -88,9 +88,7 @@ export async function processMarkdownContent(originalContent, token, replacement
     normalizeGitHubUrls(tree);
     const githubUrls = collectGitHubLinks(tree);
     const repoInfoMap = await fetchTargetData(githubUrls, repos);
-    // The title derives from the *source* repository (originalRepository), never
-    // the enhanced/mirror repo — otherwise the org name doubles into the title.
-    const { sections, title: rawTitle, titleHeadingIndex, } = processTree(tree, repoInfoMap, sortOptions, originalRepository);
+    const { sections, title: rawTitle, titleHeadingIndex, } = processTree(tree, repoInfoMap, sortOptions, originalRepositoryInfo);
     // Single source of truth for the document title: brand it once and use the
     // same value for the markdown H1 and metadata.title (parity).
     const title = brandingEnabled ? brandTitle(rawTitle) : rawTitle;
@@ -99,8 +97,9 @@ export async function processMarkdownContent(originalContent, token, replacement
     }
     const metadata = {
         last_updated: now.toISOString(),
-        original_repository: originalRepository.trim(),
-        original_repository_id: originalRepositoryId ?? null,
+        original_repository_info: originalRepositoryInfo
+            ? toRepoInfo(originalRepositoryInfo)
+            : null,
         original_repository_sha: (originalRepositorySha?.trim() ?? '') || null,
         enhanced_repository: (enhancedRepository?.trim() ?? '') || null,
         enhanced_repository_description: (enhancedRepositoryDescription?.trim() ?? '') || null,
@@ -519,14 +518,23 @@ sectionGateOpen) {
     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.
+// Title with the fallbacks every entry source shares: the split's own text
+// when it names something; else the own link's label when meaningful; else —
+// for a degenerate base (rank/year cell, URL label, tag word) owner/name, for
+// an absent base (an image-only link) the repo name. A degenerate base with
+// no live repo link (a group) keeps its text: nothing better exists.
 function entryTitle(base, ownLink, repoInfo) {
-    return (base ||
-        (ownLink ? getInlineText(ownLink.children) : '') ||
-        repoInfo?.repo ||
-        '');
+    if (base && !isDegenerateTitle(base)) {
+        return base;
+    }
+    const linkText = ownLink ? getInlineText(ownLink.children) : '';
+    if (isMeaningfulLinkText(linkText)) {
+        return linkText;
+    }
+    if (base === '') {
+        return repoInfo?.repo ?? '';
+    }
+    return repoInfo ? `${repoInfo.owner}/${repoInfo.repo}` : base;
 }
 // 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
@@ -560,15 +568,27 @@ function processTableRows(tableNode, repoInfoMap, gateOpen) {
             }
             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);
+            // A degenerate first cell (a rank/year column) moves the title source to
+            // the link's own cell: that cell no longer feeds the description — its
+            // label became the title — and the degenerate cell drops as noise.
+            const linkCellIndex = isDegenerateTitle(firstCellText.title)
+                ? cellLinks.findIndex(link => link === ownLink)
+                : -1;
+            const titleText = linkCellIndex === -1
+                ? firstCellText
+                : splitEntryText(row.children[linkCellIndex].children);
+            const description = [
+                titleText.description,
+                ...row.children
+                    .slice(1)
+                    .filter((_cell, index) => index + 1 !== linkCellIndex)
+                    .map(cell => getNodeText(cell)),
+            ]
+                .join(' ')
+                .trim();
             items.push(...emitEntryNodes(ownLink.url, repoInfo, {
-                title: entryTitle(firstCellText.title, ownLink, repoInfo),
-                description: [firstCellText.description, ...restCellsText]
-                    .join(' ')
-                    .trim(),
+                title: entryTitle(titleText.title, ownLink, repoInfo),
+                description,
             }, []));
             continue;
         }
@@ -605,6 +625,26 @@ 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;
+// A title that names nothing — the degenerate families every entry source can
+// emit: a pure number/punctuation run (a table's rank or year column, "15."
+// / "2023" / "2025-05" / "-"), a URL (a link whose label is the URL itself,
+// scheme or scheme-less `github.com/…`), or a bare tag word ("GitHub",
+// "Source code" — best-of's generated lines). CJK labels are letters
+// (`\p{L}`) and stay titles.
+const URL_TITLE = /^(?:[a-z][a-z0-9+.-]*:\/\/|www\.)\S+$|^github\.com\/\S+$/i;
+function isDegenerateTitle(title) {
+    const trimmed = title.trim();
+    return (!!trimmed &&
+        (URL_TITLE.test(trimmed) ||
+            TAG_LINK_TEXT.test(trimmed) ||
+            !/[\p{L}]/u.test(trimmed)));
+}
+// A link label that can serve as a title. The degenerate shapes are excluded
+// twice over — a URL label stays a URL, and a tag label names the link's role
+// ("[Github](repo)"), not the repo.
+function isMeaningfulLinkText(text) {
+    return text !== '' && !isDegenerateTitle(text);
+}
 // 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.
@@ -771,22 +811,6 @@ const INVALID_TITLE_PATTERNS = [
     /^video$/i,
     /^science/i,
 ];
-function repoNameFromIdentifier(identifier) {
-    const trimmed = identifier.trim();
-    if (!trimmed) {
-        return '';
-    }
-    if (/^https?:\/\//i.test(trimmed)) {
-        const parts = trimmed
-            .replace(/\.git$/i, '')
-            .replace(/[?#].*$/, '')
-            .split('/')
-            .filter(Boolean);
-        return parts[parts.length - 1] ?? '';
-    }
-    const slashIndex = trimmed.lastIndexOf('/');
-    return slashIndex === -1 ? trimmed : trimmed.slice(slashIndex + 1);
-}
 function formatRepoNameAsTitle(repoName) {
     const cleaned = repoName.replace(/[-_]/g, ' ').replace(/\s+/g, ' ').trim();
     if (/^awesome\s+/i.test(cleaned)) {
@@ -870,7 +894,7 @@ function applyBrandingToTree(tree, title, titleHeadingIndex) {
         tree.children.unshift(heading);
     }
 }
-function processTree(tree, repoInfoMap, sortOptions, originalRepository) {
+function processTree(tree, repoInfoMap, sortOptions, originalRepositoryInfo) {
     // Remember the title H1's index so branding replaces the exact same node;
     // scope matches branding/section-building so they can't drift apart.
     const titleHeadingIndex = findTitleHeadingIndex(tree);
@@ -881,11 +905,8 @@ function processTree(tree, repoInfoMap, sortOptions, originalRepository) {
     // 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.
-    if (documentTitle === '' && originalRepository) {
-        const repoName = repoNameFromIdentifier(originalRepository);
-        if (repoName) {
-            documentTitle = formatRepoNameAsTitle(repoName);
-        }
+    if (documentTitle === '' && originalRepositoryInfo) {
+        documentTitle = formatRepoNameAsTitle(originalRepositoryInfo.repo);
     }
     const sectionDepth = findSectionDepth(tree, titleSlotIndex);
     const gateForSection = sectionGatePasses(tree, titleSlotIndex, sectionDepth, repoInfoMap, sortOptions);

package/dist/orchestrator.d.ts

@@ -1,4 +1,5 @@
 import { Logger } from './logger.js';
+import type { RepoInfoDetails } from './github.js';
 import { JsonOutput, ReplacementRule } from './markdown.js';
 export interface EnhanceOptions {
     content: string;
@@ -8,11 +9,9 @@ export interface EnhanceOptions {
     /** Defaults to the console sink; pass your own (e.g. an Actions workflow-command sink) to route diagnostics. */
     log?: Logger;
     now?: Date;
-    originalRepository: string;
-    originalRepositoryId?: number;
+    originalRepositoryInfo?: null | RepoInfoDetails;
     originalRepositorySha?: string;
     relativeLinkPrefix?: string;
-    /** Text substitutions applied to the source before it is parsed. */
     replacements?: ReplacementRule[];
     sortBy?: '' | 'last_commit' | 'stars';
     token: string;

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

package/package.json

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