Add the github_project_v2 table

docs/tables/github_project_v2.md

@@ -0,0 +1,238 @@
+---
+title: "Steampipe Table: github_project_v2 - Query GitHub Projects (V2) using SQL"
+description: "Allows users to query GitHub Projects (V2), providing insights into the organization and user projects used to plan and track work."
+folder: "Project"
+---
+
+# Table: github_project_v2 - Query GitHub Projects (V2) using SQL
+
+GitHub Projects (V2) is GitHub's flexible, table and board based tool for planning and tracking work across issues and pull requests. It allows teams to organize work items, track status, and view progress across one or more repositories using customizable views, fields, and workflows.
+
+## Table Usage Guide
+
+The `github_project_v2` table provides insights into ProjectsV2 owned by a GitHub organization or user. As a project manager or developer, explore project-specific details through this table, including title, description, visibility, status, linked repositories, and linked teams. Utilize it to uncover information about projects, such as which ones are public, which repositories and teams are associated with them, and when they were last updated.
+
+To query this table using a [fine-grained access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token), the following permissions are required:
+  - Organization permissions:
+    - Projects (Read-only): Required to access all columns.
+    - Members (Read-only): Required for the `teams` column to return team slugs; without it, GitHub redacts team nodes the token can't see and returns empty strings (e.g. `["", ""]`) instead of the real slugs.
+
+**Important Notes**
+- You must specify either the `organization` or the `user_login` column in a `where` or `join` clause to query the table (projects owned by a repository are not currently supported).
+
+## Examples
+
+### List the projects in an organization
+Explore the title, state, and visibility of the ProjectsV2 owned by a specific GitHub organization to get an overview of ongoing work.
+
+```sql+postgres
+select
+  organization,
+  number,
+  title,
+  state,
+  is_public,
+  created_at
+from
+  github_project_v2
+where
+  organization = 'turbot';
+```
+
+```sql+sqlite
+select
+  organization,
+  number,
+  title,
+  state,
+  is_public,
+  created_at
+from
+  github_project_v2
+where
+  organization = 'turbot';
+```
+
+### List open projects in an organization
+Identify the projects that are still open in a specific organization, to help focus attention on active planning boards.
+
+```sql+postgres
+select
+  organization,
+  number,
+  title,
+  created_at,
+  updated_at
+from
+  github_project_v2
+where
+  organization = 'turbot'
+  and state = 'open';
+```
+
+```sql+sqlite
+select
+  organization,
+  number,
+  title,
+  created_at,
+  updated_at
+from
+  github_project_v2
+where
+  organization = 'turbot'
+  and state = 'open';
+```
+
+### Get a specific project by number
+Retrieve the details of a single project using its project number, useful when you already know which project you want to inspect.
+
+```sql+postgres
+select
+  number,
+  title,
+  description,
+  owner,
+  creator
+from
+  github_project_v2
+where
+  organization = 'turbot'
+  and number = 1;
+```
+
+```sql+sqlite
+select
+  number,
+  title,
+  description,
+  owner,
+  creator
+from
+  github_project_v2
+where
+  organization = 'turbot'
+  and number = 1;
+```
+
+### List projects updated in the last 30 days
+Discover the projects that have had recent activity, useful for tracking which planning boards are actively being maintained.
+
+```sql+postgres
+select
+  number,
+  title,
+  updated_at
+from
+  github_project_v2
+where
+  organization = 'turbot'
+  and updated_at >= now() - interval '30 days'
+order by
+  updated_at desc;
+```
+
+```sql+sqlite
+select
+  number,
+  title,
+  updated_at
+from
+  github_project_v2
+where
+  organization = 'turbot'
+  and updated_at >= datetime('now', '-30 days')
+order by
+  updated_at desc;
+```
+
+### List repositories and teams linked to each project
+Explore which repositories and teams are linked to each project, to understand the scope of collaboration around a project.
+
+```sql+postgres
+select
+  number,
+  title,
+  repositories,
+  repositories_total_count,
+  teams,
+  teams_total_count
+from
+  github_project_v2
+where
+  organization = 'turbot';
+```
+
+```sql+sqlite
+select
+  number,
+  title,
+  repositories,
+  repositories_total_count,
+  teams,
+  teams_total_count
+from
+  github_project_v2
+where
+  organization = 'turbot';
+```
+
+### List the latest status update for each project
+Explore the most recent status update posted on each project, useful for quickly checking the reported health and progress of a project.
+
+```sql+postgres
+select
+  number,
+  title,
+  latest_status_update ->> 'status' as status,
+  latest_status_update ->> 'body' as body,
+  latest_status_update ->> 'created_at' as reported_at
+from
+  github_project_v2
+where
+  organization = 'turbot';
+```
+
+```sql+sqlite
+select
+  number,
+  title,
+  json_extract(latest_status_update, '$.status') as status,
+  json_extract(latest_status_update, '$.body') as body,
+  json_extract(latest_status_update, '$.created_at') as reported_at
+from
+  github_project_v2
+where
+  organization = 'turbot';
+```
+
+### List the projects owned by a user
+Explore the title, state, and visibility of the ProjectsV2 owned by a specific GitHub user, e.g. your own personal projects.
+
+```sql+postgres
+select
+  user_login,
+  number,
+  title,
+  state,
+  is_public,
+  created_at
+from
+  github_project_v2
+where
+  user_login = 'octocat';
+```
+
+```sql+sqlite
+select
+  user_login,
+  number,
+  title,
+  state,
+  is_public,
+  created_at
+from
+  github_project_v2
+where
+  user_login = 'octocat';
+```

github/issue_pr_utils.go

@@ -158,6 +158,7 @@ func appendIssueColumnIncludes(m *map[string]interface{}, cols []string) {
 	(*m)["includeIssueNodeId"] = githubv4.Boolean(slices.Contains(cols, "node_id"))
 	(*m)["includeIssueId"] = githubv4.Boolean(slices.Contains(cols, "id"))
 	(*m)["includeIssueIsReadByUser"] = githubv4.Boolean(slices.Contains(cols, "is_read_by_user"))
+	(*m)["includeIssueProjectsV2"] = githubv4.Boolean(slices.Contains(cols, "projects_v2") || slices.Contains(cols, "projects_v2_total_count"))
 }
 
 func issueHydrateIsReadByUser(_ context.Context, _ *plugin.QueryData, h *plugin.HydrateData) (interface{}, error) {
@@ -472,6 +473,25 @@ func issueHydrateLabels(_ context.Context, _ *plugin.QueryData, h *plugin.Hydrat
 	return issue.Labels.Nodes, nil
 }
 
+func issueHydrateProjectsV2(_ context.Context, _ *plugin.QueryData, h *plugin.HydrateData) (interface{}, error) {
+	issue, err := extractIssueFromHydrateItem(h)
+	if err != nil {
+		return nil, err
+	}
+	if len(issue.ProjectsV2.Nodes) == 0 {
+		return nil, nil
+	}
+	return issue.ProjectsV2.Nodes, nil
+}
+
+func issueHydrateProjectsV2TotalCount(_ context.Context, _ *plugin.QueryData, h *plugin.HydrateData) (interface{}, error) {
+	issue, err := extractIssueFromHydrateItem(h)
+	if err != nil {
+		return nil, err
+	}
+	return issue.ProjectsV2.TotalCount, nil
+}
+
 func extractIssueCommentFromHydrateItem(h *plugin.HydrateData) (models.IssueComment, error) {
 	if issueComment, ok := h.Item.(models.IssueComment); ok {
 		return issueComment, nil

github/models/issue.go

@@ -49,6 +49,20 @@ type Issue struct {
 		TotalCount int
 		Nodes      []BaseUser
 	} `graphql:"assignees(first: 10) @include(if:$includeIssueAssignees)" json:"assignees"`
+	ProjectsV2 struct {
+		TotalCount int
+		Nodes      []struct {
+			Id        string       `graphql:"id: fullDatabaseId" json:"id"`
+			NodeId    string       `graphql:"nodeId: id" json:"node_id"`
+			Number    int          `json:"number"`
+			Title     string       `json:"title"`
+			Closed    bool         `json:"closed"`
+			ClosedAt  NullableTime `json:"closed_at"`
+			CreatedAt NullableTime `json:"created_at"`
+			UpdatedAt NullableTime `json:"updated_at"`
+			Url       string       `json:"url"`
+		}
+	} `graphql:"projectsV2(first: 100) @include(if:$includeIssueProjectsV2)" json:"projects_v2"`
 }
 
 type IssueTemplate struct {

github/models/project_v2.go

@@ -0,0 +1,84 @@
+package models
+
+import "encoding/json"
+
+// ProjectV2Owner represents the owner of a project, which can be an Organization or User.
+type ProjectV2Owner struct {
+	TypeName     string `graphql:"type: __typename" json:"-"`
+	Organization struct {
+		Id    int    `graphql:"id: databaseId" json:"id"`
+		Login string `json:"login"`
+	} `graphql:"... on Organization" json:"-"`
+	User struct {
+		Id    int    `graphql:"id: databaseId" json:"id"`
+		Login string `json:"login"`
+	} `graphql:"... on User" json:"-"`
+}
+
+func (o ProjectV2Owner) MarshalJSON() ([]byte, error) {
+	flat := struct {
+		Type  string `json:"type"`
+		Id    int    `json:"id"`
+		Login string `json:"login"`
+	}{
+		Type: o.TypeName,
+	}
+
+	switch o.TypeName {
+	case "Organization":
+		flat.Id = o.Organization.Id
+		flat.Login = o.Organization.Login
+	case "User":
+		flat.Id = o.User.Id
+		flat.Login = o.User.Login
+	}
+
+	return json.Marshal(flat)
+}
+
+// ProjectV2StatusUpdate represents a single status update on a project.
+type ProjectV2StatusUpdate struct {
+	Id         string       `graphql:"id: fullDatabaseId" json:"id"`
+	NodeId     string       `graphql:"nodeId: id" json:"node_id"`
+	Status     string       `json:"status"`
+	Body       string       `json:"body"`
+	StartDate  string       `json:"start_date"`
+	TargetDate string       `json:"target_date"`
+	CreatedAt  NullableTime `json:"created_at"`
+	UpdatedAt  NullableTime `json:"updated_at"`
+	Creator    Actor        `json:"creator"`
+}
+
+type ProjectV2 struct {
+	Id                 string         `graphql:"id: fullDatabaseId @include(if:$includeId)" json:"id"`
+	NodeId             string         `graphql:"nodeId: id @include(if:$includeNodeId)" json:"node_id"`
+	Number             int            `json:"number"`
+	Owner              ProjectV2Owner `graphql:"owner @include(if:$includeOwner)" json:"owner,omitempty"`
+	Creator            Actor          `graphql:"creator @include(if:$includeCreator)" json:"creator,omitempty"`
+	Title              string         `graphql:"title @include(if:$includeTitle)" json:"title"`
+	Description        string         `graphql:"description: shortDescription @include(if:$includeDescription)" json:"description"`
+	IsPublic           bool           `graphql:"public @include(if:$includeIsPublic)" json:"public"`
+	ClosedAt           NullableTime   `graphql:"closedAt @include(if:$includeClosedAt)" json:"closed_at"`
+	CreatedAt          NullableTime   `graphql:"createdAt @include(if:$includeCreatedAt)" json:"created_at"`
+	UpdatedAt          NullableTime   `graphql:"updatedAt @include(if:$includeUpdatedAt)" json:"updated_at"`
+	Closed             bool           `graphql:"closed @include(if:$includeState)" json:"closed"`
+	LatestStatusUpdate struct {
+		Nodes []ProjectV2StatusUpdate
+	} `graphql:"statusUpdates(first: 1) @include(if:$includeLatestStatusUpdate)" json:"latest_status_update"`
+	IsTemplate   bool   `graphql:"template @include(if:$includeIsTemplate)" json:"template"`
+	Readme       string `graphql:"readme @include(if:$includeReadme)" json:"readme"`
+	ResourcePath string `graphql:"resourcePath @include(if:$includeResourcePath)" json:"resource_path"`
+	Url          string `graphql:"url @include(if:$includeUrl)" json:"url"`
+	Repositories struct {
+		TotalCount int
+		Nodes      []struct {
+			NameWithOwner string `json:"name_with_owner"`
+		}
+	} `graphql:"repositories(first: 100) @include(if:$includeRepositories)" json:"repositories"`
+	Teams struct {
+		TotalCount int
+		Nodes      []struct {
+			Slug string `json:"slug"`
+		}
+	} `graphql:"teams(first: 100) @include(if:$includeTeams)" json:"teams"`
+}

github/plugin.go

@@ -58,6 +58,7 @@ func Plugin(ctx context.Context) *plugin.Plugin {
 			"github_organization_ruleset":            tableGitHubOrganizationRuleset(),
 			"github_package":                         tableGitHubPackage(),
 			"github_package_version":                 tableGitHubPackageVersion(),
+			"github_project_v2":                      tableGitHubProjectV2(),
 			"github_pull_request":                    tableGitHubPullRequest(),
 			"github_pull_request_comment":            tableGitHubPullRequestComment(),
 			"github_pull_request_review":             tableGitHubPullRequestReview(),