@enhansome/core 1.10.1 → 1.10.2

package/dist/first-seen.d.ts

@@ -0,0 +1,3 @@
+import type { JsonOutput } from './markdown.js';
+export type FirstSeen = (repoId: number) => string;
+export declare function firstSeenFor(previous: JsonOutput | undefined, now: Date): FirstSeen;

package/dist/first-seen.js

@@ -0,0 +1,20 @@
+export function firstSeenFor(previous, now) {
+    const index = new Map();
+    if (previous) {
+        for (const section of previous.items) {
+            collect(section.items, index);
+        }
+    }
+    return repoId => index.get(repoId) ?? now.toISOString();
+}
+function collect(nodes, index) {
+    for (const node of nodes) {
+        if (node.node_type === 'item' && node.first_seen) {
+            const existing = index.get(node.repo_info.id);
+            if (existing === undefined || node.first_seen < existing) {
+                index.set(node.repo_info.id, node.first_seen);
+            }
+        }
+        collect(node.children, index);
+    }
+}

package/dist/markdown.d.ts

@@ -30,6 +30,7 @@ export declare function toRepoInfo(details: RepoInfoDetails): RepoInfo;
 export interface JsonItem {
     children: JsonNode[];
     description: null | string;
+    first_seen?: string;
     node_type: 'item';
     repo_info: RepoInfo;
     title: string;
@@ -54,7 +55,7 @@ export interface JsonSection {
     items: JsonNode[];
     title: string;
 }
-export declare function processMarkdownContent(originalContent: string, token: string, replacements?: ReplacementRule[], sortOptions?: SortOptions, relativeLinkPrefix?: string, enhancedRepository?: string, enhancedRepositoryDescription?: string, originalRepositorySha?: string, originalRepositoryInfo?: null | RepoInfoDetails, 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, previousJson?: JsonOutput, now?: Date, log?: Logger): Promise<{
     finalContent: string;
     jsonData: JsonOutput;
 }>;

package/dist/markdown.js

@@ -4,6 +4,7 @@ import remarkParse from 'remark-parse';
 import remarkStringify from 'remark-stringify';
 import { unified } from 'unified';
 import { visit } from 'unist-util-visit';
+import { firstSeenFor } from './first-seen.js';
 import { formatRequestError, getRepoInfo as fetchRepoInfo, makeOctokit, parseGitHubUrl, } from './github.js';
 import { consoleLog } from './logger.js';
 /** The sole crossing from the API shape to the emitted one, so both agree on the renames. */
@@ -79,7 +80,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 }, relativeLinkPrefix = '', enhancedRepository, enhancedRepositoryDescription, originalRepositorySha, originalRepositoryInfo, now = new Date(), log = consoleLog) {
+export async function processMarkdownContent(originalContent, token, replacements = [], sortOptions = { by: '', minLinks: 2 }, relativeLinkPrefix = '', enhancedRepository, enhancedRepositoryDescription, originalRepositorySha, originalRepositoryInfo, previousJson, now = new Date(), log = consoleLog) {
     const repos = createRepoInfoLookup(token, log);
     const brandingEnabled = replacements.some(rule => rule.type === 'branding');
     const contentAfterReplacements = applyTextReplacements(originalContent, replacements.filter(rule => rule.type !== 'branding'), log);
@@ -88,7 +89,8 @@ export async function processMarkdownContent(originalContent, token, replacement
     normalizeGitHubUrls(tree);
     const githubUrls = collectGitHubLinks(tree);
     const repoInfoMap = await fetchTargetData(githubUrls, repos);
-    const { sections, title: rawTitle, titleHeadingIndex, } = processTree(tree, repoInfoMap, sortOptions, originalRepositoryInfo);
+    const firstSeen = firstSeenFor(previousJson, now);
+    const { sections, title: rawTitle, titleHeadingIndex, } = processTree(tree, repoInfoMap, sortOptions, originalRepositoryInfo, firstSeen);
     // Single source of truth for the document title: brand it once and use the
     // same value for the markdown H1 and metadata.title (parity).
     const title = brandingEnabled ? brandTitle(rawTitle) : rawTitle;
@@ -439,7 +441,7 @@ function splitEntryText(inlines) {
 // 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) {
+function emitEntryNodes(githubUrl, repoInfo, text, childrenJson, firstSeen) {
     if (githubUrl && repoInfo) {
         return [
             {
@@ -448,6 +450,7 @@ function emitEntryNodes(githubUrl, repoInfo, text, childrenJson) {
                 description: text.description || null,
                 children: childrenJson,
                 repo_info: toRepoInfo(repoInfo),
+                first_seen: firstSeen(repoInfo.id),
             },
         ];
     }
@@ -466,7 +469,7 @@ function emitEntryNodes(githubUrl, repoInfo, text, childrenJson) {
     }
     return [];
 }
-function processListRecursively(listNode, repoInfoMap, sortOptions, isNested = false, 
+function processListRecursively(listNode, repoInfoMap, sortOptions, firstSeen, 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.
@@ -493,8 +496,8 @@ sectionGateOpen) {
         // 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));
+            ? processListRecursively(child, repoInfoMap, sortOptions, firstSeen, true)
+            : processTableRows(child, repoInfoMap, true, firstSeen));
         // 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.
@@ -508,7 +511,7 @@ sectionGateOpen) {
         // The shared title fallbacks (an inline-code link label carries no text
         // nodes, so the split alone can leave an empty title).
         entryText.title = entryTitle(entryText.title, ownLink, repoInfo);
-        const emitted = emitEntryNodes(githubUrl, repoInfo, entryText, childrenJson);
+        const emitted = emitEntryNodes(githubUrl, repoInfo, entryText, childrenJson, firstSeen);
         entries.push({ emitted, node: itemNode, repoInfo });
     }
     if (sortOptions.by) {
@@ -536,18 +539,7 @@ function entryTitle(base, ownLink, repoInfo) {
     }
     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
-// 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) {
+function processTableRows(tableNode, repoInfoMap, gateOpen, firstSeen) {
     if (!gateOpen) {
         return [];
     }
@@ -589,7 +581,7 @@ function processTableRows(tableNode, repoInfoMap, gateOpen) {
             items.push(...emitEntryNodes(ownLink.url, repoInfo, {
                 title: entryTitle(titleText.title, ownLink, repoInfo),
                 description,
-            }, []));
+            }, [], firstSeen));
             continue;
         }
         const emittedUrls = new Set();
@@ -603,34 +595,15 @@ function processTableRows(tableNode, repoInfoMap, gateOpen) {
             items.push(...emitEntryNodes(ownLink.url, repoInfo, {
                 title: entryTitle(cellText.title, ownLink, repoInfo),
                 description: cellText.description,
-            }, []));
+            }, [], firstSeen));
         }
     }
     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;
-// 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();
@@ -639,9 +612,6 @@ function isDegenerateTitle(title) {
             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);
 }
@@ -757,13 +727,13 @@ function blockquoteEntries(blockquote) {
 // 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) {
+function entryNodesFor(ownLink, inlines, repoInfoMap, firstSeen) {
     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,
-    }, []);
+    }, [], firstSeen);
 }
 // The <details><summary>…</summary> collapsible-section idiom: the summary
 // text delimits structure like a heading would (java's generated README,
@@ -894,7 +864,7 @@ function applyBrandingToTree(tree, title, titleHeadingIndex) {
         tree.children.unshift(heading);
     }
 }
-function processTree(tree, repoInfoMap, sortOptions, originalRepositoryInfo) {
+function processTree(tree, repoInfoMap, sortOptions, originalRepositoryInfo, firstSeen) {
     // 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);
@@ -925,7 +895,7 @@ function processTree(tree, repoInfoMap, sortOptions, originalRepositoryInfo) {
             openImplicitSection(stack, atIndex);
         }
         if (gateForSection(stack[0])) {
-            stack[stack.length - 1].children.push(...entryNodesFor(ownLink, inlines, repoInfoMap));
+            stack[stack.length - 1].children.push(...entryNodesFor(ownLink, inlines, repoInfoMap, firstSeen));
         }
     };
     // A standalone entry restating the repo of an open item container (crypto's
@@ -952,7 +922,7 @@ function processTree(tree, repoInfoMap, sortOptions, originalRepositoryInfo) {
             const promotedEntry = headingEntry && getInlineText(headingEntry.link.children)
                 ? headingEntry
                 : null;
-            closeContainers(stack, node.depth, sectionRecords, !!promotedEntry);
+            closeContainers(stack, node.depth, sectionRecords, firstSeen, !!promotedEntry);
             openContainer(stack, node, i, sectionDepth, promotedEntry, headingEntry);
         }
         else if (node.type === 'paragraph') {
@@ -1004,7 +974,7 @@ function processTree(tree, repoInfoMap, sortOptions, originalRepositoryInfo) {
             // section, which keeps collecting after the collapsible block.
             const summaryTitle = detailsSummaryTitle(node.value);
             if (summaryTitle) {
-                closeInnermostDetails(stack, sectionRecords);
+                closeInnermostDetails(stack, sectionRecords, firstSeen);
                 // Container depths never decrease going up the stack. When the open
                 // containers sit deeper than sectionDepth (a mid-document H1 defines
                 // sectionDepth while the content sections run deeper), the
@@ -1025,7 +995,7 @@ function processTree(tree, repoInfoMap, sortOptions, originalRepositoryInfo) {
                 });
             }
             else if (DETAILS_CLOSE.test(node.value)) {
-                closeInnermostDetails(stack, sectionRecords);
+                closeInnermostDetails(stack, sectionRecords, firstSeen);
             }
         }
         else if (node.type === 'list') {
@@ -1039,7 +1009,7 @@ function processTree(tree, repoInfoMap, sortOptions, originalRepositoryInfo) {
             // Every list inside the open container contributes items — a section is
             // not closed by its first list — and the minLinks gate is decided per
             // section, against the whole section subtree.
-            const items = processListRecursively(node, repoInfoMap, sortOptions, false, gateForSection(stack[0]));
+            const items = processListRecursively(node, repoInfoMap, sortOptions, firstSeen, false, gateForSection(stack[0]));
             stack[stack.length - 1].children.push(...items);
         }
         else if (node.type === 'table') {
@@ -1049,11 +1019,11 @@ function processTree(tree, repoInfoMap, sortOptions, originalRepositoryInfo) {
             if (stack.length === 0) {
                 openImplicitSection(stack, i);
             }
-            const items = processTableRows(node, repoInfoMap, gateForSection(stack[0]));
+            const items = processTableRows(node, repoInfoMap, gateForSection(stack[0]), firstSeen);
             stack[stack.length - 1].children.push(...items);
         }
     }
-    closeContainers(stack, 0, sectionRecords);
+    closeContainers(stack, 0, sectionRecords, firstSeen);
     const sections = sectionRecords
         .sort((a, b) => a.headingIndex - b.headingIndex)
         .map(record => record.section);
@@ -1314,7 +1284,7 @@ function sectionGatePasses(tree, titleSlotIndex, sectionDepth, repoInfoMap, sort
 // 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) {
+function finalizeContainer(container, stack, sectionRecords, firstSeen) {
     if (container.children.length === 0 && container.kind !== 'item') {
         return;
     }
@@ -1334,6 +1304,7 @@ function finalizeContainer(container, stack, sectionRecords) {
             node_type: 'item',
             repo_info: toRepoInfo(container.repoInfo),
             title: container.title,
+            first_seen: firstSeen(container.repoInfo.id),
         });
     }
     else {
@@ -1351,13 +1322,13 @@ function finalizeContainer(container, stack, sectionRecords) {
 // 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) {
+function closeContainers(stack, depth, sectionRecords, firstSeen, 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);
+        finalizeContainer(stack.pop(), stack, sectionRecords, firstSeen);
     }
 }
 // Ends the innermost open details-section and everything opened inside it,
@@ -1365,7 +1336,7 @@ function closeContainers(stack, depth, sectionRecords, stopAtSynthesized = false
 // 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) {
+function closeInnermostDetails(stack, sectionRecords, firstSeen) {
     let detailsIndex = -1;
     for (let s = stack.length - 1; s >= 0; s--) {
         if (stack[s].openedByDetails) {
@@ -1377,7 +1348,7 @@ function closeInnermostDetails(stack, sectionRecords) {
         return;
     }
     while (stack.length > detailsIndex) {
-        finalizeContainer(stack.pop(), stack, sectionRecords);
+        finalizeContainer(stack.pop(), stack, sectionRecords, firstSeen);
     }
 }
 function serializeAst(tree, originalContent) {

package/dist/orchestrator.d.ts

@@ -6,11 +6,11 @@ export interface EnhanceOptions {
     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;
     originalRepositoryInfo?: null | RepoInfoDetails;
     originalRepositorySha?: string;
+    previousJson?: JsonOutput;
     relativeLinkPrefix?: string;
     replacements?: ReplacementRule[];
     sortBy?: '' | 'last_commit' | 'stars';

package/dist/orchestrator.js

@@ -1,6 +1,6 @@
 import { processMarkdownContent, } from './markdown.js';
 export async function enhance(options) {
-    const { content, disableBranding = false, log, now = new Date(), originalRepositoryInfo, originalRepositorySha, relativeLinkPrefix = '', replacements = [], sortBy = '', enhancedRepository, enhancedRepositoryDescription, token, } = options;
+    const { content, disableBranding = false, log, now = new Date(), originalRepositoryInfo, originalRepositorySha, previousJson, 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, relativeLinkPrefix, enhancedRepository, enhancedRepositoryDescription, originalRepositorySha, originalRepositoryInfo, now, log);
+    const { finalContent, jsonData } = await processMarkdownContent(content, token, rules, sortOptions, relativeLinkPrefix, enhancedRepository, enhancedRepositoryDescription, originalRepositorySha, originalRepositoryInfo, previousJson, now, log);
     return {
         finalContent,
         jsonData,

package/package.json

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