GitHub Integration

/**
 * GitHub integration and configuration
 * Manages repository settings, workflows, and automation
 */
class GitHub extends Component {
  constructor(project: GitHubProject, options?: GitHubOptions);
  
  /** GitHub Actions workflows */
  readonly workflows: Record<string, GithubWorkflow>;
  /** Issue templates */
  readonly issueTemplates: IssueTemplate[];
  /** Pull request template */
  readonly pullRequestTemplate?: PullRequestTemplate;
  
  /** Add a GitHub Actions workflow */
  addWorkflow(name: string, workflow: GithubWorkflow): void;
  /** Remove a workflow */
  removeWorkflow(name: string): void;
  /** Add issue template */
  addIssueTemplate(template: IssueTemplate): void;
  /** Add pull request template */
  addPullRequestTemplate(template: PullRequestTemplate): void;
}

interface GitHubOptions {
  /** Repository settings */
  repository?: RepositoryOptions;
  /** Issue templates */
  issueTemplates?: IssueTemplate[];
  /** Pull request template */
  pullRequestTemplate?: PullRequestTemplate;
  /** Mergify configuration */
  mergify?: boolean;
  /** Dependabot configuration */
  dependabot?: boolean;
  /** Auto-merge configuration */
  autoMerge?: boolean;
  /** Stale bot configuration */
  stale?: boolean;
}

interface RepositoryOptions {
  /** Repository description */
  description?: string;
  /** Repository topics */
  topics?: string[];
  /** Homepage URL */
  homepage?: string;
  /** Repository visibility */
  private?: boolean;
  /** Branch protection settings */
  branchProtection?: BranchProtectionOptions;
}

/**
 * Base project with GitHub features and repository management
 * Extends Project with GitHub-specific functionality
 */
class GitHubProject extends Project {
  constructor(options: GitHubProjectOptions);
  
  /** GitHub integration component */
  readonly github?: GitHub;
  /** Default release branch */
  readonly defaultReleaseBranch: string;
  /** Release workflow */
  readonly releaseWorkflow?: GithubWorkflow;
  /** Build workflow */
  readonly buildWorkflow?: GithubWorkflow;
  
  /** Add GitHub Actions workflow */
  addGitHubWorkflow(name: string, workflow: GithubWorkflow): void;
}

interface GitHubProjectOptions extends ProjectOptions {
  /** Default release branch (default: "main") */
  defaultReleaseBranch?: string;
  /** GitHub integration options */
  github?: boolean;
  /** GitHub configuration */
  githubOptions?: GitHubOptions;
  /** Enable release workflow */
  release?: boolean;
  /** Release workflow options */
  releaseOptions?: ReleaseOptions;
  /** Enable build workflow */
  buildWorkflow?: boolean;
  /** Build workflow options */
  buildWorkflowOptions?: BuildWorkflowOptions;
}

import { GitHubProject } from "projen";

const project = new GitHubProject({
  name: "my-github-project",
  defaultReleaseBranch: "main",
  
  // GitHub features
  github: true,
  githubOptions: {
    repository: {
      description: "My awesome GitHub project",
      topics: ["typescript", "projen", "automation"],
      homepage: "https://my-project.com",
    },
    mergify: true,
    dependabot: true,
    stale: true,
  },
  
  // Release automation
  release: true,
  
  // Build workflow
  buildWorkflow: true,
});

/**
 * GitHub Actions workflow definition
 * Represents a complete CI/CD workflow
 */
class GithubWorkflow extends Component {
  constructor(github: GitHub, name: string, options?: WorkflowOptions);
  
  /** Workflow name */
  readonly name: string;
  /** Workflow triggers */
  readonly triggers: WorkflowTriggers;
  /** Workflow jobs */
  readonly jobs: Record<string, Job>;
  
  /** Add workflow trigger */
  addTrigger(trigger: WorkflowTrigger): void;
  /** Add job to workflow */
  addJob(name: string, job: Job): void;
  /** Remove job from workflow */
  removeJob(name: string): void;
}

interface WorkflowOptions {
  /** Workflow triggers */
  triggers?: WorkflowTriggers;
  /** Workflow jobs */
  jobs?: Record<string, Job>;
  /** Workflow permissions */
  permissions?: WorkflowPermissions;
  /** Environment variables */
  env?: Record<string, string>;
  /** Concurrency settings */
  concurrency?: ConcurrencyOptions;
}

interface WorkflowTriggers {
  /** Push triggers */
  push?: PushTrigger;
  /** Pull request triggers */
  pullRequest?: PullRequestTrigger;
  /** Schedule triggers */
  schedule?: ScheduleTrigger[];
  /** Manual dispatch */
  workflowDispatch?: WorkflowDispatchTrigger;
  /** Repository dispatch */
  repositoryDispatch?: RepositoryDispatchTrigger;
}

interface Job {
  /** Job name */
  name?: string;
  /** Runner type */
  runsOn: string | string[];
  /** Job steps */
  steps: JobStep[];
  /** Job environment */
  env?: Record<string, string>;
  /** Job timeout */
  timeoutMinutes?: number;
  /** Job strategy */
  strategy?: JobStrategy;
  /** Job permissions */
  permissions?: JobPermissions;
  /** Job needs */
  needs?: string | string[];
  /** Job condition */
  if?: string;
}

interface JobStep {
  /** Step name */
  name?: string;
  /** Action to use */
  uses?: string;
  /** Command to run */
  run?: string;
  /** Step inputs */
  with?: Record<string, any>;
  /** Environment variables */
  env?: Record<string, string>;
  /** Step condition */
  if?: string;
  /** Continue on error */
  continueOnError?: boolean;
}

import { GitHubProject, Job } from "projen";

const project = new GitHubProject({
  name: "workflow-example",
  github: true,
});

// Create custom CI workflow
const ciJob: Job = {
  runsOn: "ubuntu-latest",
  steps: [
    {
      name: "Checkout",
      uses: "actions/checkout@v3",
    },
    {
      name: "Setup Node.js",
      uses: "actions/setup-node@v3",
      with: {
        "node-version": "18",
        "cache": "npm",
      },
    },
    {
      name: "Install dependencies",
      run: "npm ci",
    },
    {
      name: "Run tests",
      run: "npm test",
    },
    {
      name: "Build",
      run: "npm run build",
    },
  ],
};

project.github?.addWorkflow("ci", {
  triggers: {
    push: { branches: ["main"] },
    pullRequest: { branches: ["main"] },
  },
  jobs: {
    test: ciJob,
  },
});

/**
 * Dependabot configuration for automated dependency updates
 * Manages security updates and version upgrades
 */
class Dependabot extends Component {
  constructor(github: GitHub, options?: DependabotOptions);
  
  /** Add package ecosystem for updates */
  addPackageEcosystem(ecosystem: string, options?: PackageEcosystemOptions): void;
}

interface DependabotOptions {
  /** Package ecosystems to monitor */
  packageEcosystems?: PackageEcosystem[];
  /** Schedule for updates */
  scheduleInterval?: "daily" | "weekly" | "monthly";
  /** Target branch for PRs */
  targetBranch?: string;
}

interface PackageEcosystem {
  /** Package manager (npm, pip, maven, etc.) */
  packageManager: string;
  /** Directory to monitor */
  directory: string;
  /** Update schedule */
  schedule: {
    interval: "daily" | "weekly" | "monthly";
    time?: string;
    timezone?: string;
  };
  /** Reviewers for PRs */
  reviewers?: string[];
  /** Assignees for PRs */
  assignees?: string[];
  /** Labels for PRs */
  labels?: string[];
}

/**
 * Mergify configuration for advanced merge rules
 * Automates pull request merging based on conditions
 */
class Mergify extends Component {
  constructor(github: GitHub, options?: MergifyOptions);
  
  /** Add merge rule */
  addRule(rule: MergifyRule): void;
}

interface MergifyOptions {
  /** Merge rules */
  rules?: MergifyRule[];
}

interface MergifyRule {
  /** Rule name */
  name: string;
  /** Conditions for the rule */
  conditions: string[];
  /** Actions to take */
  actions: MergifyAction[];
}

interface MergifyAction {
  /** Action type */
  merge?: {
    method?: "merge" | "squash" | "rebase";
    strict?: boolean;
  };
  /** Delete head branch */
  delete_head_branch?: boolean;
  /** Add label */
  label?: {
    add?: string[];
    remove?: string[];
  };
}

/**
 * Auto-merge workflows for approved pull requests
 * Automatically merges PRs that meet criteria
 */
class AutoMerge extends Component {
  constructor(github: GitHub, options?: AutoMergeOptions);
}

/**
 * Auto-approve workflows for trusted changes
 * Automatically approves PRs from trusted sources
 */
class AutoApprove extends Component {
  constructor(github: GitHub, options?: AutoApproveOptions);
}

interface AutoMergeOptions {
  /** Required status checks */
  requiredStatusChecks?: string[];
  /** Merge method */
  mergeMethod?: "merge" | "squash" | "rebase";
  /** Delete branch after merge */
  deleteBranchAfterMerge?: boolean;
}

interface AutoApproveOptions {
  /** Trusted users/bots */
  allowedUsers?: string[];
  /** Label for auto-approval */
  label?: string;
}

/**
 * GitHub issue template configuration
 * Provides structured templates for different issue types
 */
class IssueTemplate {
  constructor(options: IssueTemplateOptions);
}

/**
 * GitHub pull request template
 * Standardizes PR descriptions and checklists
 */
class PullRequestTemplate extends Component {
  constructor(github: GitHub, options?: PullRequestTemplateOptions);
}

interface IssueTemplateOptions {
  /** Template name */
  name: string;
  /** Template description */
  about: string;
  /** Template title */
  title?: string;
  /** Template labels */
  labels?: string[];
  /** Template assignees */
  assignees?: string[];
  /** Template body */
  body: string;
}

interface PullRequestTemplateOptions {
  /** Template content */
  content: string[];
}

import { GitHubProject } from "projen";

const project = new GitHubProject({
  name: "template-example",
  github: true,
  githubOptions: {
    issueTemplates: [
      {
        name: "Bug Report",
        about: "Create a report to help us improve",
        title: "[BUG] ",
        labels: ["bug", "needs-triage"],
        body: `**Describe the bug**
A clear and concise description of what the bug is.

**To Reproduce**
Steps to reproduce the behavior:
1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
4. See error

**Expected behavior**
A clear and concise description of what you expected to happen.

**Environment**
- OS: [e.g. iOS]
- Browser [e.g. chrome, safari]
- Version [e.g. 22]`,
      },
      {
        name: "Feature Request",
        about: "Suggest an idea for this project",
        title: "[FEATURE] ",
        labels: ["enhancement"],
        body: `**Is your feature request related to a problem?**
A clear and concise description of what the problem is.

**Describe the solution you'd like**
A clear and concise description of what you want to happen.

**Additional context**
Add any other context or screenshots about the feature request here.`,
      },
    ],
    pullRequestTemplate: {
      content: [
        "## Description",
        "",
        "Brief description of the changes made.",
        "",
        "## Type of Change",
        "",
        "- [ ] Bug fix",
        "- [ ] New feature", 
        "- [ ] Breaking change",
        "- [ ] Documentation update",
        "",
        "## Testing",
        "",
        "- [ ] Tests pass locally",
        "- [ ] New tests added for changes",
        "",
        "## Checklist",
        "",
        "- [ ] Code follows style guidelines",
        "- [ ] Self-review completed",
        "- [ ] Documentation updated",
      ],
    },
  },
});

interface WorkflowPermissions {
  actions?: "read" | "write";
  checks?: "read" | "write";
  contents?: "read" | "write";
  deployments?: "read" | "write";
  issues?: "read" | "write";
  packages?: "read" | "write";
  pullRequests?: "read" | "write";
  repositoryProjects?: "read" | "write";
  securityEvents?: "read" | "write";
  statuses?: "read" | "write";
}

interface PushTrigger {
  branches?: string[];
  branchesIgnore?: string[];
  paths?: string[];
  pathsIgnore?: string[];
  tags?: string[];
  tagsIgnore?: string[];
}

interface PullRequestTrigger {
  branches?: string[];
  branchesIgnore?: string[];
  paths?: string[];
  pathsIgnore?: string[];
  types?: string[];
}

interface ScheduleTrigger {
  cron: string;
}

interface JobStrategy {
  matrix?: Record<string, any>;
  failFast?: boolean;
  maxParallel?: number;
}

interface BranchProtectionOptions {
  /** Require status checks */
  requiredStatusChecks?: string[];
  /** Require up-to-date branches */
  requireUpToDate?: boolean;
  /** Require pull request reviews */
  requiredReviewers?: number;
  /** Dismiss stale reviews */
  dismissStaleReviews?: boolean;
  /** Require code owner reviews */
  requireCodeOwnerReviews?: boolean;
  /** Restrict pushes */
  restrictPushes?: boolean;
  /** Required linear history */
  requireLinearHistory?: boolean;
}