@enhansome/core 1.6.1

package/dist/github.d.ts

@@ -0,0 +1,89 @@
+import { Octokit } from '@octokit/core';
+import { Logger } from './logger.js';
+import type { ThrottlingOptions } from '@octokit/plugin-throttling';
+declare const HardenedOctokit: typeof Octokit & import("@octokit/core/types").Constructor<import("@octokit/plugin-rest-endpoint-methods").Api & {
+    paginate: import("@octokit/plugin-paginate-rest").PaginateInterface;
+} & import("@octokit/plugin-retry").RetryPlugin>;
+export type GithubClient = InstanceType<typeof HardenedOctokit>;
+export interface RepoInfoDetails {
+    archived: boolean;
+    description: null | string;
+    language: null | string;
+    open_issues_count: number;
+    owner: string;
+    pushed_at: null | string;
+    repo: string;
+    stargazers_count: number;
+    topics: string[];
+}
+export interface RepoIdentifier {
+    owner: string;
+    repo: string;
+}
+/**
+ * Exported for unit testing; wired into the throttling plugin by `makeOctokit`.
+ *
+ * `maxWaitSeconds` caps how long a single retry will wait for a rate-limit
+ * reset. It defaults to 300s: the Action must self-bound its run time so a
+ * workflow never hangs on a limit it cannot service. Longer-lived callers raise
+ * it to wait out a reset instead of aborting into an unrecoverable 403.
+ *
+ * `maxRetries` bounds the rate-limit retry budget reported here and matches the
+ * transport-retry count set in `makeOctokit`, so the two budgets stay aligned.
+ */
+export declare function createRateLimitHandler(kind: 'primary' | 'secondary', log?: Logger, maxWaitSeconds?: number, maxRetries?: number): (retryAfter: number, reqOptions: {
+    method: string;
+    url: string;
+}, _octokit: unknown, retryCount: number) => boolean;
+type ThrottleGroup = NonNullable<ThrottlingOptions['write']>;
+/**
+ * Pass-through overrides for `@octokit/plugin-throttling`. The plugin's groups
+ * are process-wide singletons by default; supplying your own detaches this
+ * client so its limits apply per-instance instead of being shared across every
+ * Octokit in the process.
+ */
+export interface ThrottleOptions {
+    auth?: ThrottleGroup;
+    /** Secondary-rate-limit retry wait in seconds when the response carries no retry-after header (plugin default 60). */
+    fallbackSecondaryRateRetryAfter?: number;
+    global?: ThrottleGroup;
+    notifications?: ThrottleGroup;
+    search?: ThrottleGroup;
+    /** Per-request Bottleneck timeout in ms (plugin default 120_000). */
+    timeout?: number;
+    write?: ThrottleGroup;
+}
+/**
+ * Tuning for the hardened client built by `makeOctokit`. All fields optional;
+ * omitting the bag yields the Action defaults — `consoleLog`, 3 retries, a 300s
+ * rate-limit cap, and the throttling plugin's built-in limits.
+ */
+export interface MakeOctokitOptions {
+    /** Sink for debug/warn/error; defaults to `consoleLog`. */
+    log?: Logger;
+    /** Transport and rate-limit retry budget (default 3). */
+    maxRetries?: number;
+    /** Rate-limit retry-wait cap in seconds (default 300); see `createRateLimitHandler`. */
+    maxWaitSeconds?: number;
+    /** Throttling overrides forwarded into the plugin's `throttle` config. */
+    throttle?: ThrottleOptions;
+}
+/**
+ * The client is where the sink lives: Octokit takes a `log` and exposes it as
+ * `octokit.log`, so every function below reaches it through the client it is
+ * already given, instead of taking a logger of its own.
+ */
+export declare function makeOctokit(token: string, { log, maxRetries, maxWaitSeconds, throttle, }?: MakeOctokitOptions): GithubClient;
+export declare function getRepoInfo(octokit: GithubClient, owner: string, repo: string): Promise<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: ''`
+ * listing is always an array; the single-entry branch defends against a file
+ * response. */
+export declare function getRootEntryNames(octokit: GithubClient, owner: string, repo: string): Promise<string[]>;
+/** Source revision for the JSON output, so an enhanced list is traceable to its origin commit. */
+export declare function getLatestCommitSha(octokit: GithubClient, owner: string, repo: string): Promise<null | string>;
+export declare function parseOwnerRepo(value: string): null | RepoIdentifier;
+export declare function parseGitHubUrl(url: string): null | RepoIdentifier;
+export declare function formatRequestError(error: unknown): string;
+export {};

package/dist/github.js

@@ -0,0 +1,172 @@
+import { Octokit } from '@octokit/core';
+import { paginateRest } from '@octokit/plugin-paginate-rest';
+import { restEndpointMethods } from '@octokit/plugin-rest-endpoint-methods';
+import { retry } from '@octokit/plugin-retry';
+import { throttling } from '@octokit/plugin-throttling';
+import { consoleLog } from './logger.js';
+const DEFAULT_MAX_WAIT_TIME_SECONDS = 300, MAX_RETRIES = 3;
+// `@actions/github`'s `GitHub` is `Octokit.plugin(restEndpointMethods,
+// paginateRest).defaults(...)` — it pre-applies REST endpoint methods
+// (`octokit.rest.*`) and pagination. We dropped `@actions/github` to keep core
+// free of the Actions runtime, so re-apply those two plugins here alongside the
+// retry/throttling hardening, on a bare `Octokit`. Note this drops
+// `@actions/github`'s `.defaults` (GHE baseUrl + proxy agent/fetch) — acceptable
+// for the github.com + GITHUB_TOKEN path the action uses; self-hosted runners
+// behind a proxy or GHE installs would regress.
+const HardenedOctokit = Octokit.plugin(restEndpointMethods, paginateRest, retry, throttling);
+/**
+ * Exported for unit testing; wired into the throttling plugin by `makeOctokit`.
+ *
+ * `maxWaitSeconds` caps how long a single retry will wait for a rate-limit
+ * reset. It defaults to 300s: the Action must self-bound its run time so a
+ * workflow never hangs on a limit it cannot service. Longer-lived callers raise
+ * it to wait out a reset instead of aborting into an unrecoverable 403.
+ *
+ * `maxRetries` bounds the rate-limit retry budget reported here and matches the
+ * transport-retry count set in `makeOctokit`, so the two budgets stay aligned.
+ */
+export function createRateLimitHandler(kind, log = consoleLog, maxWaitSeconds = DEFAULT_MAX_WAIT_TIME_SECONDS, maxRetries = MAX_RETRIES) {
+    return (retryAfter, reqOptions, _octokit, retryCount) => {
+        const where = `${reqOptions.method} ${reqOptions.url}`;
+        if (retryAfter > maxWaitSeconds) {
+            log.error(`${kind} rate limit retry-after (${retryAfter}s) exceeds the maximum wait time of ${maxWaitSeconds}s. Aborting retries for ${where}.`);
+            return false;
+        }
+        if (retryCount >= maxRetries) {
+            log.error(`Giving up on ${where} after ${maxRetries} ${kind} rate-limit retries.`);
+            return false;
+        }
+        log.warn(`${kind} rate limit hit for ${where}. Waiting ${retryAfter}s before retry ${retryCount + 1}/${maxRetries}.`);
+        return true;
+    };
+}
+/**
+ * The client is where the sink lives: Octokit takes a `log` and exposes it as
+ * `octokit.log`, so every function below reaches it through the client it is
+ * already given, instead of taking a logger of its own.
+ */
+export function makeOctokit(token, { log = consoleLog, maxRetries = MAX_RETRIES, maxWaitSeconds, throttle, } = {}) {
+    const options = {
+        log,
+        // The throttling plugin owns rate-limit (403/429) retries, so keep them out
+        // of the retry plugin to avoid double-handling.
+        retry: {
+            doNotRetry: [400, 401, 403, 404, 410, 422, 429, 451],
+            retries: maxRetries,
+        },
+        // `throttle` spreads first so the rate-limit handlers below always win — a
+        // caller can tune Bottleneck, never replace the hardened retry policy.
+        throttle: {
+            ...throttle,
+            onRateLimit: createRateLimitHandler('primary', log, maxWaitSeconds, maxRetries),
+            onSecondaryRateLimit: createRateLimitHandler('secondary', log, maxWaitSeconds, maxRetries),
+        },
+    };
+    return token
+        ? new HardenedOctokit({ ...options, auth: token })
+        : new HardenedOctokit(options);
+}
+export async function getRepoInfo(octokit, owner, repo) {
+    octokit.log.debug(`Fetching repository info for ${owner}/${repo}`);
+    const { data } = await octokit.rest.repos.get({ owner, repo });
+    return {
+        archived: data.archived,
+        description: data.description ?? null,
+        language: data.language,
+        open_issues_count: data.open_issues_count,
+        owner: data.owner.login,
+        pushed_at: data.pushed_at,
+        repo: data.name,
+        stargazers_count: data.stargazers_count,
+        topics: data.topics ?? [],
+    };
+}
+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({
+        mediaType: { format },
+        owner,
+        repo,
+    });
+    // With `raw`/`html` media types the body is a string, but the generated types
+    // still describe the JSON shape - cast to string.
+    return response.data;
+}
+/** Root file/directory names — the compile-manifest gate reads them to tell a
+ * directory of resources from a repo that IS the deliverable. A `path: ''`
+ * listing is always an array; the single-entry branch defends against a file
+ * response. */
+export async function getRootEntryNames(octokit, owner, repo) {
+    octokit.log.debug(`Listing root directory for ${owner}/${repo}`);
+    const { data } = await octokit.rest.repos.getContent({
+        owner,
+        path: '',
+        repo,
+    });
+    const entries = Array.isArray(data) ? data : [data];
+    return entries.map(entry => entry.name);
+}
+/** Source revision for the JSON output, so an enhanced list is traceable to its origin commit. */
+export async function getLatestCommitSha(octokit, owner, repo) {
+    try {
+        octokit.log.debug(`Fetching latest commit SHA for ${owner}/${repo}`);
+        const { data } = await octokit.rest.repos.listCommits({
+            owner,
+            per_page: 1,
+            repo,
+        });
+        return data[0]?.sha ?? null;
+    }
+    catch (error) {
+        octokit.log.error(`Failed to fetch latest commit for ${owner}/${repo}: ${formatRequestError(error)}`);
+        return null;
+    }
+}
+export function parseOwnerRepo(value) {
+    const trimmed = value.trim();
+    if (!trimmed) {
+        return null;
+    }
+    if (trimmed.includes('github.com')) {
+        const url = trimmed.startsWith('http') ? trimmed : `https://${trimmed}`;
+        return parseGitHubUrl(url);
+    }
+    const parts = trimmed.split('/').filter(part => part.length > 0);
+    if (parts.length !== 2) {
+        return null;
+    }
+    return { owner: parts[0], repo: parts[1].replace(/\.git$/, '') };
+}
+export function parseGitHubUrl(url) {
+    try {
+        const parsedUrl = new URL(url);
+        if (parsedUrl.hostname !== 'github.com') {
+            return null;
+        }
+        const pathParts = parsedUrl.pathname
+            .split('/')
+            .filter(part => part.length > 0);
+        if (pathParts.length >= 2) {
+            const owner = pathParts[0], repo = pathParts[1].replace(/\.git$/, '');
+            return { owner, repo };
+        }
+        return null;
+    }
+    catch {
+        // A relative or malformed href is simply not a GitHub repo link, which is
+        // the routine case for most links in a README — not a diagnostic.
+        return null;
+    }
+}
+export function formatRequestError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const status = getErrorStatus(error);
+    return status === undefined ? message : `${status}: ${message}`;
+}
+function getErrorStatus(error) {
+    if (!!error && typeof error === 'object' && 'status' in error) {
+        const { status } = error;
+        return typeof status === 'number' && status > 0 ? status : undefined;
+    }
+    return undefined;
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { formatRequestError, getLatestCommitSha, getReadme, 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';
+export { toRepoInfo } from './markdown.js';
+export type { JsonGroup, JsonItem, JsonMetadata, JsonNode, JsonOutput, JsonSection, ReplacementRule, RepoInfo, } from './markdown.js';
+export { enhance } from './orchestrator.js';
+export type { EnhanceOptions, EnhanceResult } from './orchestrator.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { formatRequestError, getLatestCommitSha, getReadme, 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/logger.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Octokit's own log shape, which every client already carries as `octokit.log`.
+ * Reusing it — rather than inventing a second logger — is what lets the sink
+ * ride along with the client that is already passed to everything that logs.
+ */
+export interface Logger {
+    debug: (message: string) => unknown;
+    error: (message: string) => unknown;
+    info: (message: string) => unknown;
+    warn: (message: string) => unknown;
+}
+/** Library default: routes diagnostics to the console without a runner dependency. */
+export declare const consoleLog: Logger;
+/** For an embedder that wants none of the above on its stdout. */
+export declare const silentLog: Logger;

package/dist/logger.js

@@ -0,0 +1,22 @@
+/** Library default: routes diagnostics to the console without a runner dependency. */
+export const consoleLog = {
+    debug: message => {
+        console.debug(message);
+    },
+    error: message => {
+        console.error(message);
+    },
+    info: message => {
+        console.info(message);
+    },
+    warn: message => {
+        console.warn(message);
+    },
+};
+/** For an embedder that wants none of the above on its stdout. */
+export const silentLog = {
+    debug: () => undefined,
+    error: () => undefined,
+    info: () => undefined,
+    warn: () => undefined,
+};

package/dist/markdown.d.ts

@@ -0,0 +1,58 @@
+import { RepoInfoDetails } from './github.js';
+import { Logger } from './logger.js';
+export interface JsonOutput {
+    items: JsonSection[];
+    metadata: JsonMetadata;
+}
+export type ReplacementRule = {
+    find: string;
+    replace: string;
+    type: 'literal' | 'regex';
+} | {
+    type: 'branding';
+};
+export interface SortOptions {
+    by: '' | 'last_commit' | 'stars';
+    minLinks: number;
+}
+export interface RepoInfo {
+    archived: boolean;
+    language: null | string;
+    last_commit: null | string;
+    owner: string;
+    repo: string;
+    stars: number;
+}
+/** The sole crossing from the API shape to the emitted one, so both agree on the renames. */
+export declare function toRepoInfo(details: RepoInfoDetails): RepoInfo;
+export interface JsonItem {
+    children: JsonNode[];
+    description: null | string;
+    node_type: 'item';
+    repo_info?: RepoInfo;
+    title: string;
+}
+export interface JsonGroup {
+    children: JsonNode[];
+    description: null | string;
+    node_type: 'group';
+    title: string;
+}
+export type JsonNode = JsonGroup | JsonItem;
+export interface JsonMetadata {
+    enhanced_repository: null | string;
+    enhanced_repository_description: null | string;
+    last_updated: string;
+    original_repository: string;
+    original_repository_sha: null | string;
+    title: string;
+}
+export interface JsonSection {
+    description: null | string;
+    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<{
+    finalContent: string;
+    jsonData: JsonOutput;
+}>;

package/dist/markdown.js

@@ -0,0 +1,519 @@
+import * as path from 'path';
+import remarkGfm from 'remark-gfm';
+import remarkParse from 'remark-parse';
+import remarkStringify from 'remark-stringify';
+import { unified } from 'unified';
+import { visit } from 'unist-util-visit';
+import { formatRequestError, getRepoInfo as fetchRepoInfo, makeOctokit, parseGitHubUrl, } from './github.js';
+import { consoleLog } from './logger.js';
+/** The sole crossing from the API shape to the emitted one, so both agree on the renames. */
+export function toRepoInfo(details) {
+    return {
+        archived: details.archived,
+        language: details.language,
+        last_commit: details.pushed_at,
+        owner: details.owner,
+        repo: details.repo,
+        stars: details.stargazers_count,
+    };
+}
+// The lookup's single throttled client coordinates rate limits across the whole
+// pool, so this bounds in-flight targets rather than requests.
+const FETCH_CONCURRENCY = 10;
+/** Task rejections propagate, so a caller that must not abort the batch on a single failure wraps its own per-item try/catch. */
+async function forEachConcurrent(items, limit, task) {
+    const queue = Array.from(items);
+    async function worker() {
+        for (let item = queue.shift(); item !== undefined; item = queue.shift()) {
+            await task(item);
+        }
+    }
+    await Promise.all(Array.from({ length: limit }, () => worker()));
+}
+// One throttled client + a per-repo memo for the run: aliased refs (a bare link
+// and a deep `/tree/...` link into the same repo) collapse to a single fetch,
+// the same way a case-variant spelling of one repo costs one round-trip.
+function createRepoInfoLookup(token, log) {
+    const client = makeOctokit(token, { log });
+    const cache = new Map();
+    return {
+        client,
+        getRepoInfo(ref) {
+            const key = `${ref.owner.toLowerCase()}/${ref.repo.toLowerCase()}`;
+            let pending = cache.get(key);
+            if (!pending) {
+                pending = fetchRepoInfo(client, ref.owner, ref.repo);
+                cache.set(key, pending);
+            }
+            return pending;
+        },
+    };
+}
+/**
+ * Fetches repo info for every GitHub link the tree addresses by URL, keyed by
+ * URL so badge insertion can look each one up. Aliased URLs pointing at one repo
+ * collapse to a single fetch inside the lookup, then fan back out to every alias
+ * here.
+ *
+ * Each target's failure is independent and non-fatal: a dead link is skipped
+ * with a warning and its item is still emitted (no repo_info). Only the source
+ * README fetch in main.ts can fail the run.
+ */
+async function fetchTargetData(urls, repos) {
+    const log = repos.client.log;
+    const repoInfoMap = new Map();
+    const fetchStart = Date.now();
+    await forEachConcurrent(urls, FETCH_CONCURRENCY, async (url) => {
+        const details = parseGitHubUrl(url);
+        if (!details) {
+            return;
+        }
+        try {
+            repoInfoMap.set(url, await repos.getRepoInfo(details));
+        }
+        catch (error) {
+            log.warn(`Skipping repo info for ${url}: ${formatRequestError(error)}`);
+        }
+    });
+    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) {
+    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);
+    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);
+    // 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;
+    if (brandingEnabled) {
+        applyBrandingToTree(tree, title, titleHeadingIndex);
+    }
+    const metadata = {
+        last_updated: now.toISOString(),
+        original_repository: originalRepository.trim(),
+        original_repository_sha: (originalRepositorySha?.trim() ?? '') || null,
+        enhanced_repository: (enhancedRepository?.trim() ?? '') || null,
+        enhanced_repository_description: (enhancedRepositoryDescription?.trim() ?? '') || null,
+        title,
+    };
+    const jsonData = {
+        items: sections,
+        metadata,
+    };
+    addInfoBadges(tree, repoInfoMap);
+    fixRelativeLinks(tree, relativeLinkPrefix);
+    let finalContent = serializeAst(tree, originalContent);
+    if (brandingEnabled) {
+        finalContent = appendEnhansomedFooter(finalContent, now);
+    }
+    return {
+        finalContent,
+        jsonData,
+    };
+}
+function addInfoBadges(tree, repoInfoMap) {
+    const modifications = new Map();
+    visit(tree, 'link', (node, index, parent) => {
+        if (index === undefined || !parent) {
+            return;
+        }
+        const repoInfo = repoInfoMap.get(node.url);
+        if (!repoInfo) {
+            return;
+        }
+        const badgeNode = {
+            type: 'text',
+            value: createBadgeText(repoInfo),
+        };
+        if (!modifications.has(parent)) {
+            modifications.set(parent, []);
+        }
+        modifications.get(parent)?.push({ index: index + 1, node: badgeNode });
+    });
+    for (const [parent, changes] of modifications.entries()) {
+        changes.sort((a, b) => b.index - a.index);
+        for (const { index, node } of changes) {
+            parent.children.splice(index, 0, node);
+        }
+    }
+}
+function applyTextReplacements(content, rules, log) {
+    let processedContent = content;
+    for (const rule of rules) {
+        if (rule.type === 'literal') {
+            log.debug(`Applying literal replacement: '${rule.find}' -> '${rule.replace}'`);
+            processedContent = processedContent.replaceAll(rule.find, rule.replace);
+        }
+        else if (rule.type === 'regex') {
+            try {
+                const regex = new RegExp(rule.find, 'gm');
+                log.debug(`Applying regex replacement: /${rule.find}/gm -> '${rule.replace}'`);
+                processedContent = processedContent.replace(regex, rule.replace);
+            }
+            catch (e) {
+                log.warn(`Skipping invalid regex pattern '${rule.find}': ${e instanceof Error ? e.message : e}`);
+            }
+        }
+        // 'branding' rules are applied to the AST/title downstream, not here.
+    }
+    return processedContent;
+}
+function collectGitHubLinks(tree) {
+    const urls = new Set();
+    visit(tree, 'link', (node) => {
+        if (parseGitHubUrl(node.url)) {
+            urls.add(node.url);
+        }
+    });
+    return urls;
+}
+function createBadgeText(info) {
+    if (info.archived) {
+        return ' ⚠️ Archived';
+    }
+    const parts = [
+        `⭐ ${info.stargazers_count.toLocaleString()}`,
+        `🐛 ${info.open_issues_count.toLocaleString()}`,
+    ];
+    if (info.language) {
+        parts.push(`🌐 ${info.language}`);
+    }
+    if (info.pushed_at) {
+        parts.push(`📅 ${formatDate(info.pushed_at)}`);
+    }
+    return ` ${parts.join(' | ')}`;
+}
+function findFirstGitHubLink(node) {
+    let linkUrl;
+    visit(node, 'link', (linkNode) => {
+        if (!linkUrl && parseGitHubUrl(linkNode.url)) {
+            linkUrl = linkNode.url;
+        }
+    });
+    return linkUrl;
+}
+// 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
+// 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.
+// `[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;
+}
+function fixRelativeLinks(tree, relativeLinkPrefix) {
+    if (!relativeLinkPrefix) {
+        return;
+    }
+    if (relativeLinkPrefix) {
+        visit(tree, 'link', node => {
+            if (!node.url.startsWith('http') &&
+                !node.url.startsWith('/') &&
+                !node.url.startsWith('#')) {
+                node.url = path.join(relativeLinkPrefix, node.url).replace(/\\/g, '/');
+            }
+        });
+    }
+}
+function formatDate(isoString) {
+    if (!isoString) {
+        return '';
+    }
+    return new Date(isoString).toISOString().split('T')[0];
+}
+function getNodeText(node) {
+    return getInlineText([node]);
+}
+// Concatenates text descendants, collapsing whitespace (incl. a lone soft-break
+// newline) to one space. Takes a node slice so callers can isolate text
+// before/after a specific child.
+function getInlineText(nodes) {
+    let text = '';
+    for (const node of nodes) {
+        visit(node, 'text', (textNode) => {
+            text += textNode.value;
+        });
+    }
+    return text.replace(/\s+/g, ' ').trim();
+}
+// Strip one leading separator (dash, pipe, colon, middot) from the prose
+// trailing a link, but stay tightly scoped so a meaningful leading character
+// (e.g. "(" in "(deprecated) …") survives.
+function stripLeadingNoise(text) {
+    return text.replace(/^\s*[-–—·|:]\s*/, '').trim();
+}
+// Missing repo info sinks below nodes that have it; two missing tie so a stable
+// sort keeps source order. The single comparator shared by the JSON builder and
+// the AST sorter, so both outputs agree on order.
+function compareByRepoInfo(by, a, b) {
+    if (!by) {
+        return 0;
+    }
+    // Must precede the field access below (a/b may be null).
+    if (!a || !b) {
+        return a ? -1 : b ? 1 : 0;
+    }
+    if (by === 'stars') {
+        return b.stargazers_count - a.stargazers_count;
+    }
+    // `by` is narrowed to 'last_commit' here (the only remaining option).
+    const timeA = a.pushed_at ? new Date(a.pushed_at).getTime() : 0;
+    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 [];
+    }
+    // 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.
+    const entries = [];
+    for (const itemNode of listNode.children) {
+        const githubUrl = findOwnGitHubLink(itemNode);
+        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 jsonData = null;
+        if (githubUrl) {
+            const item = {
+                node_type: 'item',
+                title,
+                description: description || null,
+                children: childrenJson,
+            };
+            if (repoInfo) {
+                item.repo_info = toRepoInfo(repoInfo);
+            }
+            jsonData = item;
+        }
+        else if (childrenJson.length > 0) {
+            jsonData = {
+                node_type: 'group',
+                title,
+                description: description || null,
+                children: childrenJson,
+            };
+        }
+        entries.push({ json: jsonData, 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);
+}
+const INVALID_TITLE_PATTERNS = [
+    /^contributing/i,
+    /^license$/i,
+    /^resources$/i,
+    /^contents$/i,
+    /^table of contents$/i,
+    /^other awesome/i,
+    /^other awesomeness$/i,
+    /^communities/i,
+    /^guides$/i,
+    /^tools$/i,
+    /^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)) {
+        return cleaned.replace(/^awesome\s+/i, 'Awesome ');
+    }
+    return `Awesome ${cleaned}`;
+}
+function isValidTitle(title) {
+    if (!title || title.trim() === '') {
+        return false;
+    }
+    return !INVALID_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();
+    if (!trimmed) {
+        return trimmed;
+    }
+    if (/\bawesome\b/i.test(trimmed)) {
+        return `${trimmed} with stars`;
+    }
+    return `Awesome ${trimmed} with stars`;
+}
+// Shared by title extraction and branding so both act on the very same heading.
+function findTitleHeadingIndex(tree) {
+    return tree.children.findIndex((node) => node.type === 'heading' &&
+        node.depth === 1 &&
+        isValidTitle(getNodeText(node)));
+}
+/**
+ * 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
+ * freshly injected one) so the branded title is always the sole title H1.
+ */
+function applyBrandingToTree(tree, title, titleHeadingIndex) {
+    if (!title.trim()) {
+        return;
+    }
+    const heading = {
+        type: 'heading',
+        depth: 1,
+        children: [{ type: 'text', value: title }],
+    };
+    if (titleHeadingIndex !== -1) {
+        tree.children[titleHeadingIndex] = heading;
+        return;
+    }
+    // No valid title H1 anywhere: override the first H1 (the de-facto title slot)
+    // rather than unshifting alongside it, which would leave two H1s. Inject at
+    // the top only when the source has no H1 at all.
+    const firstH1Index = tree.children.findIndex((node) => node.type === 'heading' && node.depth === 1);
+    if (firstH1Index !== -1) {
+        tree.children[firstH1Index] = heading;
+    }
+    else {
+        tree.children.unshift(heading);
+    }
+}
+function processTree(tree, repoInfoMap, sortOptions, originalRepository) {
+    // 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);
+    let documentTitle = titleHeadingIndex === -1
+        ? ''
+        : getNodeText(tree.children[titleHeadingIndex]);
+    // 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);
+        }
+    }
+    const sections = [];
+    let currentSection = null;
+    for (const node of tree.children) {
+        if (node.type === 'heading' && node.depth > 1) {
+            if (currentSection) {
+                sections.push(currentSection);
+            }
+            currentSection = {
+                description: '',
+                items: [],
+                title: getNodeText(node),
+            };
+        }
+        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 === 'list') {
+            // No active section: not part of any JSON section, but still sort its AST
+            // so the rendered markdown matches.
+            processListRecursively(node, repoInfoMap, sortOptions);
+        }
+    }
+    if (currentSection) {
+        sections.push(currentSection);
+    }
+    return { sections, title: documentTitle, titleHeadingIndex };
+}
+function serializeAst(tree, originalContent) {
+    let finalContent = unified()
+        .use(remarkStringify)
+        .use(remarkGfm)
+        .stringify(tree);
+    const originalHadNewline = originalContent.endsWith('\n') || originalContent === '';
+    if (finalContent.endsWith('\n') && !originalHadNewline) {
+        finalContent = finalContent.slice(0, -1);
+    }
+    else if (!finalContent.endsWith('\n') && originalHadNewline) {
+        finalContent += '\n';
+    }
+    return finalContent;
+}
+function appendEnhansomedFooter(content, now) {
+    const date = now.toISOString().split('T')[0];
+    const footer = `***\n\n> _Enhansomed by [enhansome](https://github.com/enhansome) on ${date}._`;
+    const body = content.replace(/\n+$/, '');
+    return `${body}\n\n${footer}\n`;
+}

package/dist/orchestrator.d.ts

@@ -0,0 +1,23 @@
+import { Logger } from './logger.js';
+import { JsonOutput, ReplacementRule } from './markdown.js';
+export interface EnhanceOptions {
+    content: string;
+    disableBranding?: boolean;
+    enhancedRepository?: string;
+    enhancedRepositoryDescription?: string;
+    /** Defaults to the console sink; pass your own (e.g. an Actions workflow-command sink) to route diagnostics. */
+    log?: Logger;
+    now?: Date;
+    originalRepository: string;
+    originalRepositorySha?: string;
+    relativeLinkPrefix?: string;
+    /** Text substitutions applied to the source before it is parsed. */
+    replacements?: ReplacementRule[];
+    sortBy?: '' | 'last_commit' | 'stars';
+    token: string;
+}
+export interface EnhanceResult {
+    finalContent: string;
+    jsonData: JsonOutput;
+}
+export declare function enhance(options: EnhanceOptions): Promise<EnhanceResult>;

package/dist/orchestrator.js

@@ -0,0 +1,17 @@
+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;
+    // 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' };
+    const rules = disableBranding ? replacements : [branding, ...replacements];
+    const sortOptions = {
+        by: sortBy,
+        minLinks: 2,
+    };
+    const { finalContent, jsonData } = await processMarkdownContent(content, token, rules, sortOptions, originalRepository, relativeLinkPrefix, enhancedRepository, enhancedRepositoryDescription, originalRepositorySha, now, log);
+    return {
+        finalContent,
+        jsonData,
+    };
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@enhansome/core",
+  "version": "1.6.1",
+  "description": "Library core for enhansome — enhance markdown with GitHub star counts.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:update-goldens": "UPDATE_GOLDENS=1 vitest run"
+  },
+  "dependencies": {
+    "@octokit/core": "^7.0.6",
+    "@octokit/plugin-paginate-rest": "^14.0.0",
+    "@octokit/plugin-rest-endpoint-methods": "^17.0.0",
+    "@octokit/plugin-retry": "^8.1.0",
+    "@octokit/plugin-throttling": "^11.0.3",
+    "remark-gfm": "^4.0.1",
+    "remark-parse": "^11.0.0",
+    "remark-stringify": "^11.0.0",
+    "unified": "^11.0.5",
+    "unist-util-visit": "^5.1.0"
+  },
+  "devDependencies": {
+    "@octokit/request-error": "^7.1.0",
+    "@types/mdast": "^4.0.4",
+    "@types/node": "^26.1.0",
+    "@types/unist": "^3.0.3",
+    "@vitest/coverage-v8": "^4.1.9",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9"
+  },
+  "packageManager": "yarn@4.17.1+sha512.ccbfabf7d7b6b32075088be9386fb9a2e00bb6887ef07fa56effabc890a56d53da1ccc4128d62db245fcbd3961b236d75335bdf7d5320ed6eafb7588b7ad4697"
+}