@larkiny/astro-github-loader 0.12.0 → 0.14.0

package/README.md

@@ -1,5 +1,12 @@
 # Astro GitHub Loader
 
+[![CI](https://github.com/larkiny/starlight-github-loader/actions/workflows/ci.yml/badge.svg)](https://github.com/larkiny/starlight-github-loader/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@larkiny/astro-github-loader?style=flat-square)](https://www.npmjs.com/package/@larkiny/astro-github-loader)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![Built with Astro](https://img.shields.io/badge/Astro-BC52EE?style=flat-square&logo=astro&logoColor=white)](https://astro.build)
+[![Built with Starlight](https://img.shields.io/badge/Starlight-FFC517?style=flat-square&logo=astro&logoColor=black)](https://starlight.astro.build)
+[![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+
 Load content from GitHub repositories into Astro content collections with flexible pattern-based import, asset management, content transformations, and intelligent change detection.
 
 ## Features

package/dist/github.dryrun.js

@@ -6,6 +6,9 @@ const STATE_FILENAME = ".github-import-state.json";
  * Creates a unique identifier for an import configuration
  */
 export function createConfigId(config) {
+    if (config.stateKey) {
+        return config.stateKey;
+    }
     return `${config.owner}/${config.repo}@${config.ref || "main"}`;
 }
 /**

package/dist/github.link-transform.js

@@ -87,6 +87,11 @@ function applyLinkMappings(linkUrl, linkMappings, context) {
         }
         let matched = false;
         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)) {
@@ -95,8 +100,7 @@ function applyLinkMappings(linkUrl, linkMappings, context) {
                     replacement = transformedPath.replace(mapping.pattern, mapping.replacement);
                 }
                 else {
-                    const linkTransformContext = context.currentFile.linkContext ?? {};
-                    replacement = mapping.replacement(transformedPath, anchor, linkTransformContext);
+                    replacement = mapping.replacement(transformedPath, anchor, getLinkTransformContext());
                 }
             }
         }
@@ -109,8 +113,7 @@ function applyLinkMappings(linkUrl, linkMappings, context) {
                     replacement = transformedPath.replace(mapping.pattern, mapping.replacement);
                 }
                 else {
-                    const linkTransformContext = context.currentFile.linkContext ?? {};
-                    replacement = mapping.replacement(transformedPath, anchor, linkTransformContext);
+                    replacement = mapping.replacement(transformedPath, anchor, getLinkTransformContext());
                 }
             }
         }

package/dist/github.storage.d.ts

@@ -2,9 +2,10 @@ import type { ImportedFile } from "./github.link-transform.js";
 import type { ExtendedLoaderContext } from "./github.types.js";
 /**
  * Ensures directory exists and writes file to disk.
+ * Validates that the resolved path stays within the project root.
  * @internal
  */
-export declare function syncFile(path: string, content: string): Promise<void>;
+export declare function syncFile(filePath: string, content: string): Promise<void>;
 /**
  * Stores a processed file in Astro's content store
  * @internal

package/dist/github.storage.js

@@ -1,15 +1,21 @@
 import { existsSync, promises as fs } from "node:fs";
+import { resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 /**
  * Ensures directory exists and writes file to disk.
+ * Validates that the resolved path stays within the project root.
  * @internal
  */
-export async function syncFile(path, content) {
-    const dir = path.substring(0, path.lastIndexOf("/"));
+export async function syncFile(filePath, content) {
+    const resolved = resolve(filePath);
+    if (!resolved.startsWith(process.cwd())) {
+        throw new Error(`syncFile: path "${filePath}" resolves outside project root`);
+    }
+    const dir = resolved.substring(0, resolved.lastIndexOf("/"));
     if (dir && !existsSync(dir)) {
         await fs.mkdir(dir, { recursive: true });
     }
-    await fs.writeFile(path, content, "utf-8");
+    await fs.writeFile(resolved, content, "utf-8");
 }
 /**
  * Stores a processed file in Astro's content store

package/dist/github.types.d.ts

@@ -234,6 +234,8 @@ export interface VersionConfig {
     slug: string;
     /** Display name for this version (e.g., "Latest", "v8.0.0") */
     label: string;
+    /** Git ref this version was sourced from (e.g., "main", "release/v7"). Optional metadata — not used by the loader. */
+    ref?: string;
 }
 /**
  * Represents configuration options for importing content from GitHub repositories.
@@ -243,6 +245,12 @@ export type ImportOptions = {
      * Display name for this configuration (used in logging)
      */
     name?: string;
+    /**
+     * Custom state key for import tracking. When provided, overrides the default
+     * `owner/repo@ref` key used to track import state. This allows the same repo
+     * to be imported independently to multiple locations.
+     */
+    stateKey?: string;
     /**
      * Repository owner
      */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@larkiny/astro-github-loader",
   "type": "module",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Load content from GitHub repositories into Astro content collections with asset management and content transformations",
   "keywords": [
     "astro",

package/src/github.dryrun.spec.ts

@@ -51,6 +51,18 @@ describe("github.dryrun", () => {
       expect(id).toBe("algorand/docs@main");
     });
 
+    it("should use custom stateKey when provided", () => {
+      const config: ImportOptions = {
+        owner: "algorandfoundation",
+        repo: "puya",
+        ref: "devportal",
+        stateKey: "puya-legacy-guides",
+        includes: [],
+      };
+
+      expect(createConfigId(config)).toBe("puya-legacy-guides");
+    });
+
     it("should handle different refs correctly", () => {
       const config: ImportOptions = {
         name: "Test Repo",

package/src/github.dryrun.ts

@@ -57,6 +57,9 @@ export interface RepositoryChangeInfo {
  * Creates a unique identifier for an import configuration
  */
 export function createConfigId(config: ImportOptions): string {
+  if (config.stateKey) {
+    return config.stateKey;
+  }
   return `${config.owner}/${config.repo}@${config.ref || "main"}`;
 }
 

package/src/github.link-transform.ts

@@ -189,6 +189,13 @@ function applyLinkMappings(
     let matched = false;
     let replacement = "";
 
+    const getLinkTransformContext = (): LinkTransformContext =>
+      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)) {
@@ -199,12 +206,10 @@ function applyLinkMappings(
             mapping.replacement,
           );
         } else {
-          const linkTransformContext =
-            context.currentFile.linkContext ?? ({} as LinkTransformContext);
           replacement = mapping.replacement(
             transformedPath,
             anchor,
-            linkTransformContext,
+            getLinkTransformContext(),
           );
         }
       }
@@ -219,12 +224,10 @@ function applyLinkMappings(
             mapping.replacement,
           );
         } else {
-          const linkTransformContext =
-            context.currentFile.linkContext ?? ({} as LinkTransformContext);
           replacement = mapping.replacement(
             transformedPath,
             anchor,
-            linkTransformContext,
+            getLinkTransformContext(),
           );
         }
       }

package/src/github.storage.spec.ts

@@ -1,4 +1,5 @@
 import { beforeEach, describe, it, expect, vi } from "vitest";
+import { resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { syncFile, storeProcessedFile } from "./github.storage.js";
 import { createMockContext } from "./test-helpers.js";
@@ -40,12 +41,14 @@ describe("syncFile", () => {
   it("creates directory and writes file when directory does not exist", async () => {
     await syncFile("some/nested/dir/file.md", "content");
 
-    expect(mockedExistsSync).toHaveBeenCalledWith("some/nested/dir");
-    expect(mockedMkdir).toHaveBeenCalledWith("some/nested/dir", {
+    const resolved = resolve("some/nested/dir/file.md");
+    const resolvedDir = resolved.substring(0, resolved.lastIndexOf("/"));
+    expect(mockedExistsSync).toHaveBeenCalledWith(resolvedDir);
+    expect(mockedMkdir).toHaveBeenCalledWith(resolvedDir, {
       recursive: true,
     });
     expect(mockedWriteFile).toHaveBeenCalledWith(
-      "some/nested/dir/file.md",
+      resolved,
       "content",
       "utf-8",
     );
@@ -56,10 +59,12 @@ describe("syncFile", () => {
 
     await syncFile("existing/dir/file.md", "content");
 
-    expect(mockedExistsSync).toHaveBeenCalledWith("existing/dir");
+    const resolved = resolve("existing/dir/file.md");
+    const resolvedDir = resolved.substring(0, resolved.lastIndexOf("/"));
+    expect(mockedExistsSync).toHaveBeenCalledWith(resolvedDir);
     expect(mockedMkdir).not.toHaveBeenCalled();
     expect(mockedWriteFile).toHaveBeenCalledWith(
-      "existing/dir/file.md",
+      resolved,
       "content",
       "utf-8",
     );
@@ -68,10 +73,9 @@ describe("syncFile", () => {
   it("skips mkdir when path has no directory component", async () => {
     await syncFile("file.md", "content");
 
-    // dir is "" which is falsy, so existsSync should not be called for dir check
-    expect(mockedMkdir).not.toHaveBeenCalled();
+    // resolved path still has a directory (cwd), but it exists
     expect(mockedWriteFile).toHaveBeenCalledWith(
-      "file.md",
+      resolve("file.md"),
       "content",
       "utf-8",
     );
@@ -82,11 +86,17 @@ describe("syncFile", () => {
     await syncFile("output/test.md", longContent);
 
     expect(mockedWriteFile).toHaveBeenCalledWith(
-      "output/test.md",
+      resolve("output/test.md"),
       longContent,
       "utf-8",
     );
   });
+
+  it("rejects paths that escape project root", async () => {
+    await expect(
+      syncFile("../../etc/passwd", "malicious"),
+    ).rejects.toThrow("resolves outside project root");
+  });
 });
 
 describe("storeProcessedFile", () => {

package/src/github.storage.ts

@@ -1,18 +1,26 @@
 import { existsSync, promises as fs } from "node:fs";
+import { resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import type { ImportedFile } from "./github.link-transform.js";
 import type { ExtendedLoaderContext } from "./github.types.js";
 
 /**
  * Ensures directory exists and writes file to disk.
+ * Validates that the resolved path stays within the project root.
  * @internal
  */
-export async function syncFile(path: string, content: string) {
-  const dir = path.substring(0, path.lastIndexOf("/"));
+export async function syncFile(filePath: string, content: string) {
+  const resolved = resolve(filePath);
+  if (!resolved.startsWith(process.cwd())) {
+    throw new Error(
+      `syncFile: path "${filePath}" resolves outside project root`,
+    );
+  }
+  const dir = resolved.substring(0, resolved.lastIndexOf("/"));
   if (dir && !existsSync(dir)) {
     await fs.mkdir(dir, { recursive: true });
   }
-  await fs.writeFile(path, content, "utf-8");
+  await fs.writeFile(resolved, content, "utf-8");
 }
 
 /**

package/src/github.types.ts

@@ -261,6 +261,8 @@ export interface VersionConfig {
   slug: string;
   /** Display name for this version (e.g., "Latest", "v8.0.0") */
   label: string;
+  /** Git ref this version was sourced from (e.g., "main", "release/v7"). Optional metadata — not used by the loader. */
+  ref?: string;
 }
 
 /**
@@ -271,6 +273,12 @@ export type ImportOptions = {
    * Display name for this configuration (used in logging)
    */
   name?: string;
+  /**
+   * Custom state key for import tracking. When provided, overrides the default
+   * `owner/repo@ref` key used to track import state. This allows the same repo
+   * to be imported independently to multiple locations.
+   */
+  stateKey?: string;
   /**
    * Repository owner
    */