Git Integration

/**
 * Custom error thrown when git is not found in PATH
 */
class GitNotFoundError extends Error {
  constructor(message?: string);
}

/**
 * Custom error thrown when file is not tracked by git
 */
class FileNotTrackedError extends Error {
  constructor(message?: string);
}

/**
 * Last update information with timestamp and author
 */
type LastUpdateData = {
  lastUpdatedAt: number | undefined | null;
  lastUpdatedBy: string | undefined | null;
};

/**
 * Front matter format for last update information
 */
type FrontMatterLastUpdate = {
  author?: string;
  date?: Date | string;
};

/**
 * Fallback last update data for development/testing
 */
const LAST_UPDATE_FALLBACK: LastUpdateData;

/**
 * Gets git commit date for a file without author information
 * @param file - Absolute path to the file
 * @param args - Options for commit retrieval
 * @param args.age - "oldest" for first commit, "newest" for last commit
 * @param args.includeAuthor - Must be false or undefined for this overload
 * @returns Promise resolving to commit data with date and timestamp
 * @throws GitNotFoundError when git is not found
 * @throws FileNotTrackedError when file is not tracked by git
 */
function getFileCommitDate(
  file: string,
  args: {
    age?: "oldest" | "newest";
    includeAuthor?: false;
  }
): Promise<{
  date: Date;
  timestamp: number;
}>;

/**
 * Gets git commit date for a file with author information
 * @param file - Absolute path to the file
 * @param args - Options for commit retrieval
 * @param args.age - "oldest" for first commit, "newest" for last commit
 * @param args.includeAuthor - Must be true for this overload
 * @returns Promise resolving to commit data with date, timestamp, and author
 * @throws GitNotFoundError when git is not found
 * @throws FileNotTrackedError when file is not tracked by git
 */
function getFileCommitDate(
  file: string,
  args: {
    age?: "oldest" | "newest";
    includeAuthor: true;
  }
): Promise<{
  date: Date;
  timestamp: number;
  author: string;
}>;

import { 
  getFileCommitDate, 
  GitNotFoundError, 
  FileNotTrackedError 
} from "@docusaurus/utils";

try {
  // Get last commit date without author
  const lastCommit = await getFileCommitDate("/path/to/file.md", {
    age: "newest",
    includeAuthor: false,
  });
  console.log(`Last modified: ${lastCommit.date.toISOString()}`);
  console.log(`Timestamp: ${lastCommit.timestamp}`);

  // Get first commit date with author
  const firstCommit = await getFileCommitDate("/path/to/file.md", {
    age: "oldest",
    includeAuthor: true,
  });
  console.log(`Created by: ${firstCommit.author}`);
  console.log(`Created on: ${firstCommit.date.toISOString()}`);
  console.log(`Timestamp: ${firstCommit.timestamp}`);

} catch (error) {
  if (error instanceof GitNotFoundError) {
    console.error("Git is not installed or not found in PATH");
  } else if (error instanceof FileNotTrackedError) {
    console.error("File is not tracked by git");
  } else {
    console.error("Git command failed:", error.message);
  }
}

/**
 * Gets last update data from git for a specific file path
 * @param filePath - Path to the file
 * @returns Promise resolving to last update data or null if not available
 */
function getGitLastUpdate(filePath: string): Promise<LastUpdateData | null>;

/**
 * Gets last update data, using fallback in development or when disabled
 * @param filePath - Path to the file
 * @returns Promise resolving to last update data or null
 */
function getLastUpdate(filePath: string): Promise<LastUpdateData | null>;

/**
 * Reads last update data combining git information with front matter overrides
 * @param filePath - Path to the file
 * @param options - Last update display options
 * @param options.showLastUpdateAuthor - Whether to include author information
 * @param options.showLastUpdateTime - Whether to include timestamp information
 * @param lastUpdateFrontMatter - Front matter override data (optional)
 * @returns Promise resolving to combined last update data
 */
function readLastUpdateData(
  filePath: string,
  options: {
    showLastUpdateAuthor?: boolean;
    showLastUpdateTime?: boolean;
  },
  lastUpdateFrontMatter?: FrontMatterLastUpdate
): Promise<LastUpdateData>;

import { 
  getGitLastUpdate, 
  getLastUpdate, 
  readLastUpdateData,
  LAST_UPDATE_FALLBACK 
} from "@docusaurus/utils";

// Get git last update
const gitUpdate = await getGitLastUpdate("/docs/intro.md");
if (gitUpdate) {
  console.log(`Last updated: ${new Date(gitUpdate.lastUpdatedAt).toISOString()}`);
  console.log(`Author: ${gitUpdate.lastUpdatedBy}`);
} else {
  console.log("No git history available");
}

// Get last update with fallback
const lastUpdate = await getLastUpdate("/docs/intro.md");
// Will use LAST_UPDATE_FALLBACK in development or when git is unavailable

// Read last update with front matter override
const frontMatterOverride = {
  author: "John Doe",
  date: "2023-12-01",
};

const combinedUpdate = await readLastUpdateData(
  "/docs/intro.md",
  {
    showLastUpdateAuthor: true,
    showLastUpdateTime: true,
  },
  frontMatterOverride
);

console.log("Combined update data:", combinedUpdate);
// Front matter values take precedence over git data

// Using the fallback constant
console.log("Fallback data:", LAST_UPDATE_FALLBACK);
// Provides default values when git information is unavailable

import { 
  getFileCommitDate, 
  GitNotFoundError, 
  FileNotTrackedError 
} from "@docusaurus/utils";

async function safeGetCommitDate(filePath: string) {
  try {
    return await getFileCommitDate(filePath, { 
      age: "newest", 
      includeAuthor: true 
    });
  } catch (error) {
    if (error instanceof GitNotFoundError) {
      // Handle missing git installation
      console.warn("Git not found, using current date");
      return {
        date: new Date(),
        timestamp: Date.now(),
        author: "Unknown",
      };
    } else if (error instanceof FileNotTrackedError) {
      // Handle untracked files
      console.warn(`File ${filePath} not tracked by git`);
      return null;
    } else {
      // Handle other git errors
      console.error(`Git error for ${filePath}:`, error.message);
      throw error;
    }
  }
}