Types

/**
 * Base interface for commit objects with known properties.
 */
interface CommitKnownProps {
  /** Type of commit (e.g., 'feat', 'fix', 'docs') */
  type?: string | null;
  /** Full commit header/message */
  header?: string | null;
  /** Version tag if this commit represents a release */
  version?: string | null;
  /** Git commit hash */
  hash?: string | null;
  /** ISO date string of when commit was made */
  committerDate?: string | null;
  /** Array of commit notes (e.g., breaking changes) */
  notes: CommitNote[];
  /** Revert information if this is a revert commit */
  revert?: AnyObject | null;
  /** Commit body text */
  body?: string | null;
  /** Commit footer text */
  footer?: string | null;
}

/**
 * Commit object after transformation, includes reference to original.
 */
type TransformedCommit<Commit> = Commit & {
  /** Original commit before transformation */
  raw?: Commit;
};

/**
 * Detailed output containing both changelog and key commit information.
 */
interface Details<Commit extends CommitKnownProps = CommitKnownProps> {
  /** Generated changelog string */
  log: string;
  /** The key commit that triggered this changelog block */
  keyCommit: Commit | null;
}

/**
 * A note attached to a commit (e.g., BREAKING CHANGE).
 */
interface CommitNote {
  /** Title of the note (e.g., 'BREAKING CHANGE') */
  title: string;
  /** Content/description of the note */
  text: string;
}

/**
 * A group of related commits with a title.
 */
interface CommitGroup<Commit extends CommitKnownProps = CommitKnownProps> {
  /** Group title (e.g., 'Features', 'Bug Fixes') */
  title: string;
  /** Array of commits in this group */
  commits: Commit[];
}

/**
 * A group of related commit notes.
 */
interface NoteGroup {
  /** Group title (e.g., 'BREAKING CHANGES') */
  title: string;
  /** Array of notes in this group */
  notes: CommitNote[];
}

/**
 * Generic object type allowing any string keys with any values.
 */
type AnyObject = Record<string, any>;

/**
 * Comparison function type for sorting operations.
 * Returns negative for a < b, positive for a > b, zero for equality.
 */
type Comparator<T> = (a: T, b: T) => number;

/**
 * Record type with string keys and optional string values.
 */
type StringsRecord<T extends string> = { [K in T]?: string | undefined };

/**
 * Utility type that extracts keys whose values are strings.
 */
type PickStringsKeys<T> = {
  [P in keyof T]: P extends string ? T[P] extends string ? (string extends T[P] ? P : never) : never : never
}[keyof T];

/**
 * Utility type that creates a record with only string properties.
 */
type PickStrings<T> = StringsRecord<PickStringsKeys<T>>;

interface Context<Commit extends CommitKnownProps = CommitKnownProps> {
  version?: string;
  isPatch?: boolean;
  title?: string;
  date?: string;
  linkReferences?: boolean;
  commit?: string;
  issue?: string;
  repository?: string;
  host?: string;
  owner?: string;
  repoUrl?: string;
  commitGroups?: CommitGroup<Commit>[];
  noteGroups?: NoteGroup[];
  linkCompare?: boolean;
}

/**
 * Context interface with required properties set after final processing.
 */
interface FinalContext<Commit extends CommitKnownProps = CommitKnownProps> extends Context<Commit> {
  /** Required commit base URL */
  commit: string;
  /** Required issue base URL */
  issue: string;
  /** Required date */
  date: string;
}

/**
 * Type for specifying how to sort objects - by key(s) or custom function.
 */
type SortBy<T> = PickStringsKeys<T> | PickStringsKeys<T>[] | Comparator<T>;

/**
 * Function type for transforming commits during processing.
 */
type CommitTransformFunction<Commit extends CommitKnownProps = CommitKnownProps> =
  (
    commit: Commit,
    context: FinalContext<Commit>,
    options: FinalOptions<Commit>
  ) => Partial<Commit> | null | Promise<Partial<Commit> | null>;

/**
 * Function type for determining when to generate a changelog block.
 */
type GenerateOnFunction<Commit extends CommitKnownProps = CommitKnownProps> =
  (
    keyCommit: Commit,
    commitsGroup: Commit[],
    context: FinalContext<Commit>,
    options: FinalOptions<Commit>
  ) => boolean;

interface TemplatesOptions {
  mainTemplate?: string;
  headerPartial?: string;
  commitPartial?: string;
  footerPartial?: string;
  partials?: Record<string, string | null>;
}

/**
 * Template options with all required properties set.
 */
interface FinalTemplatesOptions extends TemplatesOptions {
  mainTemplate: string;
  headerPartial: string;
  commitPartial: string;
  footerPartial: string;
}

interface Options<Commit extends CommitKnownProps = CommitKnownProps> extends TemplatesOptions {
  groupBy?: keyof Commit;
  commitsSort?: SortBy<Commit>;
  commitGroupsSort?: SortBy<CommitGroup<Commit>>;
  notesSort?: SortBy<CommitNote>;
  noteGroupsSort?: SortBy<NoteGroup>;
  ignoreReverted?: boolean;
  reverse?: boolean;
  doFlush?: boolean;
  transform?: CommitTransformFunction<Commit>;
  generateOn?: GenerateOnFunction<Commit> | keyof Commit | null;
  finalizeContext?(
    context: FinalContext<Commit>,
    options: FinalOptions<Commit>,
    filteredCommits: Commit[],
    keyCommit: Commit | null,
    commits: Commit[]
  ): FinalContext<Commit> | Promise<FinalContext<Commit>>;
  debug?(message: string): void;
  formatDate?(date: string | Date): string;
  skip?(commit: Commit): boolean;
}

/**
 * Final options with all defaults applied and functions resolved.
 */
interface FinalOptions<Commit extends CommitKnownProps = CommitKnownProps> extends Options<Commit> {
  groupBy: keyof Commit;
  generateOn: GenerateOnFunction<Commit> | keyof Commit | null;
  finalizeContext: (
    context: FinalContext<Commit>,
    options: FinalOptions<Commit>,
    filteredCommits: Commit[],
    keyCommit: Commit | null,
    commits: Commit[]
  ) => FinalContext<Commit> | Promise<FinalContext<Commit>>;
  debug: (message: string) => void;
  formatDate: (date: string | Date) => string;
  transform: CommitTransformFunction<Commit>;
  commitsSort?: Comparator<Commit>;
  commitGroupsSort?: Comparator<CommitGroup<Commit>>;
  notesSort?: Comparator<CommitNote>;
  noteGroupsSort?: Comparator<NoteGroup>;
  skip?: (commit: Commit) => boolean;
  mainTemplate: string;
  headerPartial: string;
  commitPartial: string;
  footerPartial: string;
}

import { type CommitKnownProps, type CommitNote } from "conventional-changelog-writer";

// Create a properly typed commit
const commit: CommitKnownProps = {
  type: "feat",
  header: "feat(auth): add OAuth2 support",
  version: null,
  hash: "abcdef123456",
  committerDate: "2023-01-15T10:30:00Z",
  notes: [
    {
      title: "BREAKING CHANGE",
      text: "OAuth configuration format has changed"
    } as CommitNote
  ],
  revert: null,
  body: "Implemented OAuth2 authentication flow",
  footer: "Closes #123"
};

import { type CommitKnownProps } from "conventional-changelog-writer";

// Extend the base commit interface
interface CustomCommit extends CommitKnownProps {
  author?: string;
  scope?: string;
  subject?: string;
  references?: Array<{
    action: string;
    owner: string | null;
    repository: string | null;
    issue: string;
    raw: string;
  }>;
  priority?: 'low' | 'medium' | 'high';
}

// Use with generic functions
const customCommits: CustomCommit[] = [
  {
    type: "feat",
    header: "feat(auth): add login",
    author: "john.doe@example.com",
    scope: "auth",
    subject: "add login",
    priority: "high",
    version: null,
    hash: "abc123",
    committerDate: "2023-01-15",
    notes: [],
    body: null,
    footer: null,
    references: [{
      action: "Closes",
      owner: null,
      repository: null,
      issue: "123",
      raw: "#123"
    }]
  }
];

// Type-safe usage with custom commits
const result = await writeChangelogString<CustomCommit>(
  customCommits,
  context,
  {
    groupBy: "scope", // TypeScript knows this is valid
    transform: (commit, context, options) => {
      // TypeScript knows commit has all CustomCommit properties
      return {
        authorInitials: commit.author?.split('@')[0].charAt(0).toUpperCase(),
        priorityLabel: commit.priority === 'high' ? '🔥' : '📝'
      };
    }
  }
);

import { type CommitKnownProps, type CommitNote } from "conventional-changelog-writer";

// Type guard for valid commits
function isValidCommit(obj: any): obj is CommitKnownProps {
  return (
    typeof obj === 'object' &&
    obj !== null &&
    Array.isArray(obj.notes) &&
    obj.notes.every((note: any) => 
      typeof note.title === 'string' && typeof note.text === 'string'
    )
  );
}

// Type-safe commit processing
function processCommits(rawCommits: unknown[]): CommitKnownProps[] {
  return rawCommits.filter(isValidCommit);
}

// Type assertion with validation
function parseCommitFromJSON(json: string): CommitKnownProps {
  const parsed = JSON.parse(json);
  
  if (!isValidCommit(parsed)) {
    throw new Error('Invalid commit structure');
  }
  
  return parsed;
}