@larkiny/astro-github-loader 0.11.3 → 0.13.0

package/dist/github.dryrun.d.ts

@@ -1,3 +1,5 @@
+import { Octokit } from "octokit";
+import type { Logger } from "./github.logger.js";
 import type { ImportOptions, LoaderContext } from "./github.types.js";
 /**
  * Represents the state of a single import configuration
@@ -49,11 +51,11 @@ export declare function createConfigId(config: ImportOptions): string;
 /**
  * Loads the import state from the state file
  */
-export declare function loadImportState(workingDir: string): Promise<StateFile>;
+export declare function loadImportState(workingDir: string, logger?: Logger): Promise<StateFile>;
 /**
  * Gets the latest commit information for a repository path
  */
-export declare function getLatestCommitInfo(octokit: any, config: ImportOptions, signal?: AbortSignal): Promise<{
+export declare function getLatestCommitInfo(octokit: Octokit, config: ImportOptions, signal?: AbortSignal): Promise<{
     sha: string;
     message: string;
     date: string;
@@ -61,12 +63,14 @@ export declare function getLatestCommitInfo(octokit: any, config: ImportOptions,
 /**
  * Updates the import state after a successful import
  */
-export declare function updateImportState(workingDir: string, config: ImportOptions, commitSha?: string): Promise<void>;
+export declare function updateImportState(workingDir: string, config: ImportOptions, commitSha?: string, logger?: Logger): Promise<void>;
 /**
  * Performs a dry run check on all configured repositories
  */
-export declare function performDryRun(configs: ImportOptions[], context: LoaderContext, octokit: any, workingDir?: string, signal?: AbortSignal): Promise<RepositoryChangeInfo[]>;
+export declare function performDryRun(configs: ImportOptions[], context: LoaderContext, octokit: Octokit, workingDir?: string, signal?: AbortSignal): Promise<RepositoryChangeInfo[]>;
 /**
  * Formats and displays the dry run results
  */
-export declare function displayDryRunResults(results: RepositoryChangeInfo[], logger: any): void;
+export declare function displayDryRunResults(results: RepositoryChangeInfo[], logger: {
+    info: (msg: string) => void;
+}): void;

package/dist/github.dryrun.js

@@ -1,46 +1,64 @@
 import { promises as fs } from "node:fs";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
-const STATE_FILENAME = '.github-import-state.json';
+const STATE_FILENAME = ".github-import-state.json";
 /**
  * Creates a unique identifier for an import configuration
  */
 export function createConfigId(config) {
-    return `${config.owner}/${config.repo}@${config.ref || 'main'}`;
+    if (config.stateKey) {
+        return config.stateKey;
+    }
+    return `${config.owner}/${config.repo}@${config.ref || "main"}`;
 }
 /**
  * Loads the import state from the state file
  */
-export async function loadImportState(workingDir) {
+export async function loadImportState(workingDir, logger) {
     const statePath = join(workingDir, STATE_FILENAME);
     if (!existsSync(statePath)) {
         return {
             imports: {},
-            lastChecked: new Date().toISOString()
+            lastChecked: new Date().toISOString(),
         };
     }
     try {
-        const content = await fs.readFile(statePath, 'utf-8');
-        return JSON.parse(content);
+        const content = await fs.readFile(statePath, "utf-8");
+        const parsed = JSON.parse(content);
+        // Validate the parsed state has the expected shape
+        if (!parsed ||
+            typeof parsed !== "object" ||
+            !("imports" in parsed) ||
+            typeof parsed.imports !== "object") {
+            const msg = `Malformed state file at ${statePath}, starting fresh`;
+            // eslint-disable-next-line no-console -- fallback when no logger provided
+            logger ? logger.warn(msg) : console.warn(msg);
+            return { imports: {}, lastChecked: new Date().toISOString() };
+        }
+        return parsed;
     }
     catch (error) {
-        console.warn(`Failed to load import state from ${statePath}, starting fresh:`, error);
+        const msg = `Failed to load import state from ${statePath}, starting fresh: ${error}`;
+        // eslint-disable-next-line no-console -- fallback when no logger provided
+        logger ? logger.warn(msg) : console.warn(msg);
         return {
             imports: {},
-            lastChecked: new Date().toISOString()
+            lastChecked: new Date().toISOString(),
         };
     }
 }
 /**
  * Saves the import state to the state file
  */
-async function saveImportState(workingDir, state) {
+async function saveImportState(workingDir, state, logger) {
     const statePath = join(workingDir, STATE_FILENAME);
     try {
-        await fs.writeFile(statePath, JSON.stringify(state, null, 2), 'utf-8');
+        await fs.writeFile(statePath, JSON.stringify(state, null, 2), "utf-8");
     }
     catch (error) {
-        console.warn(`Failed to save import state to ${statePath}:`, error);
+        const msg = `Failed to save import state to ${statePath}: ${error}`;
+        // eslint-disable-next-line no-console -- fallback when no logger provided
+        logger ? logger.warn(msg) : console.warn(msg);
     }
 }
 /**
@@ -55,7 +73,7 @@ export async function getLatestCommitInfo(octokit, config, signal) {
             repo,
             sha: ref,
             per_page: 1,
-            request: { signal }
+            request: { signal },
         });
         if (data.length === 0) {
             return null;
@@ -63,12 +81,17 @@ export async function getLatestCommitInfo(octokit, config, signal) {
         const latestCommit = data[0];
         return {
             sha: latestCommit.sha,
-            message: latestCommit.commit.message.split('\n')[0], // First line only
-            date: latestCommit.commit.committer?.date || latestCommit.commit.author?.date || new Date().toISOString()
+            message: latestCommit.commit.message.split("\n")[0], // First line only
+            date: latestCommit.commit.committer?.date ||
+                latestCommit.commit.author?.date ||
+                new Date().toISOString(),
         };
     }
     catch (error) {
-        if (error.status === 404) {
+        if (typeof error === "object" &&
+            error !== null &&
+            "status" in error &&
+            error.status === 404) {
             throw new Error(`Repository not found: ${owner}/${repo}`);
         }
         throw error;
@@ -86,17 +109,18 @@ async function checkRepositoryForChanges(octokit, config, currentState, signal)
                 config,
                 state: currentState,
                 needsReimport: false,
-                error: "No commits found in repository"
+                error: "No commits found in repository",
             };
         }
-        const needsReimport = !currentState.lastCommitSha || currentState.lastCommitSha !== latestCommit.sha;
+        const needsReimport = !currentState.lastCommitSha ||
+            currentState.lastCommitSha !== latestCommit.sha;
         return {
             config,
             state: currentState,
             needsReimport,
             latestCommitSha: latestCommit.sha,
             latestCommitMessage: latestCommit.message,
-            latestCommitDate: latestCommit.date
+            latestCommitDate: latestCommit.date,
         };
     }
     catch (error) {
@@ -104,15 +128,15 @@ async function checkRepositoryForChanges(octokit, config, currentState, signal)
             config,
             state: currentState,
             needsReimport: false,
-            error: error.message
+            error: error instanceof Error ? error.message : String(error),
         };
     }
 }
 /**
  * Updates the import state after a successful import
  */
-export async function updateImportState(workingDir, config, commitSha) {
-    const state = await loadImportState(workingDir);
+export async function updateImportState(workingDir, config, commitSha, logger) {
+    const state = await loadImportState(workingDir, logger);
     const configId = createConfigId(config);
     const configName = config.name || `${config.owner}/${config.repo}`;
     state.imports[configId] = {
@@ -120,9 +144,9 @@ export async function updateImportState(workingDir, config, commitSha) {
         repoId: configId,
         lastCommitSha: commitSha,
         lastImported: new Date().toISOString(),
-        ref: config.ref || 'main'
+        ref: config.ref || "main",
     };
-    await saveImportState(workingDir, state);
+    await saveImportState(workingDir, state, logger);
 }
 /**
  * Performs a dry run check on all configured repositories
@@ -145,7 +169,7 @@ export async function performDryRun(configs, context, octokit, workingDir = proc
         const currentState = state.imports[configId] || {
             name: configName,
             repoId: configId,
-            ref: config.ref || 'main'
+            ref: config.ref || "main",
         };
         logger.debug(`Checking ${configName}...`);
         try {
@@ -159,7 +183,7 @@ export async function performDryRun(configs, context, octokit, workingDir = proc
                 config,
                 state: currentState,
                 needsReimport: false,
-                error: `Failed to check repository: ${error.message}`
+                error: `Failed to check repository: ${error instanceof Error ? error.message : String(error)}`,
             });
         }
     }

package/dist/github.link-transform.d.ts

@@ -1,5 +1,5 @@
-import type { LinkMapping, LinkTransformContext, IncludePattern } from './github.types.js';
-import type { Logger } from './github.logger.js';
+import type { LinkMapping, LinkTransformContext, IncludePattern } from "./github.types.js";
+import type { Logger } from "./github.logger.js";
 /**
  * Represents an imported file with its content and metadata
  */

package/dist/github.link-transform.js

@@ -1,12 +1,12 @@
-import { slug } from 'github-slugger';
-import path from 'node:path';
+import { slug } from "github-slugger";
+import path from "node:path";
 /**
  * Extract anchor fragment from a link
  */
 function extractAnchor(link) {
     const anchorMatch = link.match(/#.*$/);
-    const anchor = anchorMatch ? anchorMatch[0] : '';
-    const path = link.replace(/#.*$/, '');
+    const anchor = anchorMatch ? anchorMatch[0] : "";
+    const path = link.replace(/#.*$/, "");
     return { path, anchor };
 }
 /**
@@ -22,9 +22,9 @@ function isExternalLink(link) {
         /^ftp:/.test(link) ||
         /^ftps:\/\//.test(link) ||
         // Any protocol with ://
-        link.includes('://') ||
+        link.includes("://") ||
         // Anchor-only links (same page)
-        link.startsWith('#') ||
+        link.startsWith("#") ||
         // Data URLs
         /^data:/.test(link) ||
         // File protocol
@@ -37,7 +37,9 @@ function normalizePath(linkPath, currentFilePath, logger) {
     logger?.debug(`[normalizePath] BEFORE: linkPath="${linkPath}", currentFilePath="${currentFilePath}"`);
     // Handle relative paths (including simple relative paths without ./ prefix)
     // A link is relative if it doesn't start with / or contain a protocol
-    const isAbsoluteOrExternal = linkPath.startsWith('/') || linkPath.includes('://') || linkPath.startsWith('#');
+    const isAbsoluteOrExternal = linkPath.startsWith("/") ||
+        linkPath.includes("://") ||
+        linkPath.startsWith("#");
     if (!isAbsoluteOrExternal) {
         const currentDir = path.dirname(currentFilePath);
         const resolved = path.posix.normalize(path.posix.join(currentDir, linkPath));
@@ -63,20 +65,20 @@ function applyLinkMappings(linkUrl, linkMappings, context) {
         // Handle relative links automatically if enabled
         if (mapping.relativeLinks && context.currentFile.linkContext) {
             // Check if this is a relative link (doesn't start with /, http, etc.)
-            if (!linkPath.startsWith('/') && !isExternalLink(linkPath)) {
+            if (!linkPath.startsWith("/") && !isExternalLink(linkPath)) {
                 // Check if the link points to a known directory structure
-                const knownPaths = ['modules/', 'classes/', 'interfaces/', 'enums/'];
-                const isKnownPath = knownPaths.some(p => linkPath.startsWith(p));
+                const knownPaths = ["modules/", "classes/", "interfaces/", "enums/"];
+                const isKnownPath = knownPaths.some((p) => linkPath.startsWith(p));
                 if (isKnownPath) {
                     // Strip .md extension from the link path
-                    const cleanLinkPath = linkPath.replace(/\.md$/, '');
+                    const cleanLinkPath = linkPath.replace(/\.md$/, "");
                     // Convert relative path to absolute path using the target base
                     const targetBase = generateSiteUrl(context.currentFile.linkContext.basePath, context.global.stripPrefixes);
                     // Construct final URL with proper Starlight formatting
-                    let finalUrl = targetBase.replace(/\/$/, '') + '/' + cleanLinkPath;
+                    let finalUrl = targetBase.replace(/\/$/, "") + "/" + cleanLinkPath;
                     // Add trailing slash if it doesn't end with one and isn't empty
-                    if (finalUrl && !finalUrl.endsWith('/')) {
-                        finalUrl += '/';
+                    if (finalUrl && !finalUrl.endsWith("/")) {
+                        finalUrl += "/";
                     }
                     transformedPath = finalUrl;
                     return transformedPath + anchor;
@@ -84,16 +86,21 @@ function applyLinkMappings(linkUrl, linkMappings, context) {
             }
         }
         let matched = false;
-        let replacement = '';
-        if (typeof mapping.pattern === 'string') {
+        let replacement = "";
+        const getLinkTransformContext = () => context.currentFile.linkContext ?? {
+            sourcePath: context.currentFile.sourcePath,
+            targetPath: context.currentFile.targetPath,
+            basePath: "",
+        };
+        if (typeof mapping.pattern === "string") {
             // String pattern - exact match or contains
             if (transformedPath.includes(mapping.pattern)) {
                 matched = true;
-                if (typeof mapping.replacement === 'string') {
+                if (typeof mapping.replacement === "string") {
                     replacement = transformedPath.replace(mapping.pattern, mapping.replacement);
                 }
                 else {
-                    replacement = mapping.replacement(transformedPath, anchor, context);
+                    replacement = mapping.replacement(transformedPath, anchor, getLinkTransformContext());
                 }
             }
         }
@@ -102,11 +109,11 @@ function applyLinkMappings(linkUrl, linkMappings, context) {
             const match = transformedPath.match(mapping.pattern);
             if (match) {
                 matched = true;
-                if (typeof mapping.replacement === 'string') {
+                if (typeof mapping.replacement === "string") {
                     replacement = transformedPath.replace(mapping.pattern, mapping.replacement);
                 }
                 else {
-                    replacement = mapping.replacement(transformedPath, anchor, context);
+                    replacement = mapping.replacement(transformedPath, anchor, getLinkTransformContext());
                 }
             }
         }
@@ -131,29 +138,31 @@ function generateSiteUrl(targetPath, stripPrefixes) {
         }
     }
     // Remove leading slash if present
-    url = url.replace(/^\//, '');
+    url = url.replace(/^\//, "");
     // Remove file extension
-    url = url.replace(/\.(md|mdx)$/i, '');
+    url = url.replace(/\.(md|mdx)$/i, "");
     // Handle index files - they should resolve to parent directory
-    if (url.endsWith('/index')) {
-        url = url.replace('/index', '');
+    if (url.endsWith("/index")) {
+        url = url.replace("/index", "");
     }
-    else if (url === 'index') {
-        url = '';
+    else if (url === "index") {
+        url = "";
     }
     // Split path into segments and slugify each
-    const segments = url.split('/').map(segment => segment ? slug(segment) : '');
+    const segments = url
+        .split("/")
+        .map((segment) => (segment ? slug(segment) : ""));
     // Reconstruct URL
-    url = segments.filter(s => s).join('/');
+    url = segments.filter((s) => s).join("/");
     // Ensure leading slash
-    if (url && !url.startsWith('/')) {
-        url = '/' + url;
+    if (url && !url.startsWith("/")) {
+        url = "/" + url;
     }
     // Add trailing slash for non-empty paths
-    if (url && !url.endsWith('/')) {
-        url = url + '/';
+    if (url && !url.endsWith("/")) {
+        url = url + "/";
     }
-    return url || '/';
+    return url || "/";
 }
 /**
  * Transform a single markdown link
@@ -177,7 +186,7 @@ function transformLink(linkText, linkUrl, context) {
     // Apply global path mappings to the normalized path
     let processedNormalizedPath = normalizedPath;
     if (context.global.linkMappings) {
-        const globalMappings = context.global.linkMappings.filter(m => m.global);
+        const globalMappings = context.global.linkMappings.filter((m) => m.global);
         if (globalMappings.length > 0) {
             processedNormalizedPath = applyLinkMappings(normalizedPath + anchor, globalMappings, context);
             // Extract path again after global mappings
@@ -188,8 +197,8 @@ function transformLink(linkText, linkUrl, context) {
     // Check if this links to an imported file
     let targetPath = context.global.sourceToTargetMap.get(normalizedPath);
     // If not found and path ends with /, try looking for index.md
-    if (!targetPath && normalizedPath.endsWith('/')) {
-        targetPath = context.global.sourceToTargetMap.get(normalizedPath + 'index.md');
+    if (!targetPath && normalizedPath.endsWith("/")) {
+        targetPath = context.global.sourceToTargetMap.get(normalizedPath + "index.md");
     }
     if (targetPath) {
         // This is an internal link to an imported file
@@ -198,10 +207,10 @@ function transformLink(linkText, linkUrl, context) {
     }
     // Apply non-global path mappings to unresolved links
     if (context.global.linkMappings) {
-        const nonGlobalMappings = context.global.linkMappings.filter(m => !m.global);
+        const nonGlobalMappings = context.global.linkMappings.filter((m) => !m.global);
         if (nonGlobalMappings.length > 0) {
             const mappedUrl = applyLinkMappings(processedNormalizedPath + anchor, nonGlobalMappings, context);
-            if (mappedUrl !== (processedNormalizedPath + anchor)) {
+            if (mappedUrl !== processedNormalizedPath + anchor) {
                 return `[${linkText}](${mappedUrl})`;
             }
         }
@@ -218,7 +227,7 @@ function transformLink(linkText, linkUrl, context) {
     }
     // No transformation matched - strip .md extension from unresolved internal links
     // This handles links to files that weren't imported but should still use Starlight routing
-    const cleanPath = processedNormalizedPath.replace(/\.md$/i, '');
+    const cleanPath = processedNormalizedPath.replace(/\.md$/i, "");
     return `[${linkText}](${cleanPath + anchor})`;
 }
 /**
@@ -243,7 +252,7 @@ export function globalLinkTransform(importedFiles, options) {
     };
     // Transform links in all files
     const markdownLinkRegex = /\[([^\]]*)\]\(([^)]+)\)/g;
-    return importedFiles.map(file => ({
+    return importedFiles.map((file) => ({
         ...file,
         content: file.content.replace(markdownLinkRegex, (match, linkText, linkUrl) => {
             const linkContext = {
@@ -262,9 +271,7 @@ export function globalLinkTransform(importedFiles, options) {
  * @returns Inferred cross-section path (e.g., '/reference/api')
  */
 function inferCrossSectionPath(basePath) {
-    return basePath
-        .replace(/^src\/content\/docs/, '')
-        .replace(/\/$/, '') || '/';
+    return basePath.replace(/^src\/content\/docs/, "").replace(/\/$/, "") || "/";
 }
 /**
  * Generate link mappings automatically from pathMappings in include patterns
@@ -280,25 +287,29 @@ export function generateAutoLinkMappings(includes, stripPrefixes = []) {
         const inferredCrossSection = inferCrossSectionPath(includePattern.basePath);
         for (const [sourcePath, mappingValue] of Object.entries(includePattern.pathMappings)) {
             // Handle both string and enhanced object formats
-            const targetPath = typeof mappingValue === 'string' ? mappingValue : mappingValue.target;
-            const crossSectionPath = typeof mappingValue === 'object' && mappingValue.crossSectionPath
+            const targetPath = typeof mappingValue === "string" ? mappingValue : mappingValue.target;
+            const crossSectionPath = typeof mappingValue === "object" && mappingValue.crossSectionPath
                 ? mappingValue.crossSectionPath
                 : inferredCrossSection;
-            if (sourcePath.endsWith('/')) {
+            if (sourcePath.endsWith("/")) {
                 // Folder mapping - use regex with capture group
-                const sourcePattern = sourcePath.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+                const sourcePattern = sourcePath.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
                 linkMappings.push({
                     pattern: new RegExp(`^${sourcePattern}(.+)$`),
-                    replacement: (transformedPath, anchor, context) => {
-                        const relativePath = transformedPath.replace(new RegExp(`^${sourcePattern}`), '');
+                    replacement: (transformedPath, _anchor, _context) => {
+                        const relativePath = transformedPath.replace(new RegExp(`^${sourcePattern}`), "");
                         let finalPath;
-                        if (crossSectionPath && crossSectionPath !== '/') {
-                            finalPath = targetPath === ''
-                                ? `${crossSectionPath}/${relativePath}`
-                                : `${crossSectionPath}/${targetPath}${relativePath}`;
+                        if (crossSectionPath && crossSectionPath !== "/") {
+                            finalPath =
+                                targetPath === ""
+                                    ? `${crossSectionPath}/${relativePath}`
+                                    : `${crossSectionPath}/${targetPath}${relativePath}`;
                         }
                         else {
-                            finalPath = targetPath === '' ? relativePath : `${targetPath}${relativePath}`;
+                            finalPath =
+                                targetPath === ""
+                                    ? relativePath
+                                    : `${targetPath}${relativePath}`;
                         }
                         return generateSiteUrl(finalPath, stripPrefixes);
                     },
@@ -307,11 +318,11 @@ export function generateAutoLinkMappings(includes, stripPrefixes = []) {
             }
             else {
                 // File mapping - exact string match
-                const sourcePattern = sourcePath.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+                const sourcePattern = sourcePath.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
                 linkMappings.push({
                     pattern: new RegExp(`^${sourcePattern}$`),
-                    replacement: (transformedPath, anchor, context) => {
-                        const finalPath = crossSectionPath && crossSectionPath !== '/'
+                    replacement: (_transformedPath, _anchor, _context) => {
+                        const finalPath = crossSectionPath && crossSectionPath !== "/"
                             ? `${crossSectionPath}/${targetPath}`
                             : targetPath;
                         return generateSiteUrl(finalPath, stripPrefixes);