skrypt-ai 0.3.3 → 0.4.0

package/dist/template/src/app/docs/github/page.mdx

@@ -0,0 +1,502 @@
+## Functions
+
+### `postPRComment`
+
+```typescript
+async function postPRComment(config: PRCommentConfig, issues: DocumentationIssue[]): Promise<CommentResult>
+```
+
+Use this to automatically post documentation issue summaries as review comments on GitHub Pull Requests — ideal for CI pipelines that lint or validate docs on every PR.
+
+#### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `config` | `PRCommentConfig` | Yes | GitHub connection details including repo owner, repo name, PR number, and optional auth token |
+| `issues` | `DocumentationIssue[]` | Yes | Array of documentation issues to summarize in the PR comment |
+
+## `PRCommentConfig` Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `owner` | `string` | Yes | GitHub repository owner (user or org) |
+| `repo` | `string` | Yes | Repository name |
+| `prNumber` | `number` | Yes | Pull request number to comment on |
+| `token` | `string` | No | GitHub personal access token. Falls back to `GITHUB_TOKEN` environment variable |
+
+## `DocumentationIssue` Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `file` | `string` | Yes | Path to the file with the issue |
+| `line` | `number` | No | Line number where the issue occurs |
+| `message` | `string` | Yes | Human-readable description of the issue |
+| `severity` | `'error' \| 'warning'` | Yes | Severity level of the issue |
+
+#### Returns
+
+Returns a `Promise<CommentResult>` that resolves with:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `success` | `boolean` | Whether the comment was posted successfully |
+| `commentId` | `number` | The GitHub comment ID of the newly created comment |
+| `url` | `string` | Direct URL to the posted comment on GitHub |
+
+Throws an error if the GitHub API request fails (e.g., invalid token, repo not found, insufficient permissions).
+
+**Example:**
+
+```typescript example.ts
+// ── Inline types (no external imports needed) ──────────────────────────────
+
+type PRCommentConfig = {
+  owner: string
+  repo: string
+  prNumber: number
+  token?: string
+}
+
+type DocumentationIssue = {
+  file: string
+  line?: number
+  message: string
+  severity: 'error' | 'warning'
+}
+
+type CommentResult = {
+  success: boolean
+  commentId: number
+  url: string
+}
+
+// ── Self-contained implementation ──────────────────────────────────────────
+
+const GITHUB_API = 'https://api.github.com'
+
+async function postPRComment(
+  config: PRCommentConfig,
+  issues: DocumentationIssue[]
+): Promise<CommentResult> {
+  const token = config.token || process.env.GITHUB_TOKEN
+
+  if (!token) {
+    throw new Error(
+      'GitHub token is required. Set GITHUB_TOKEN env var or pass config.token.'
+    )
+  }
+
+  // Build a readable markdown summary of all issues
+  const errorCount = issues.filter((i) => i.severity === 'error').length
+  const warnCount = issues.filter((i) => i.severity === 'warning').length
+
+  const issueLines = issues
+    .map((issue) => {
+      const location = issue.line ? `${issue.file}:${issue.line}` : issue.file
+      const icon = issue.severity === 'error' ? '🔴' : '🟡'
+      return `- ${icon} **${location}** — ${issue.message}`
+    })
+    .join('\n')
+
+  const body = [
+    '## 📄 Documentation Review',
+    '',
+    `Found **${errorCount} error(s)** and **${warnCount} warning(s)**.`,
+    '',
+    issueLines,
+    '',
+    '_Posted automatically by autodocs._',
+  ].join('\n')
+
+  const url = `${GITHUB_API}/repos/${config.owner}/${config.repo}/issues/${config.prNumber}/comments`
+
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${token}`,
+      Accept: 'application/vnd.github+json',
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({ body }),
+  })
+
+  if (!response.ok) {
+    const errorText = await response.text()
+    throw new Error(
+      `GitHub API error ${response.status}: ${errorText}`
+    )
+  }
+
+  const data = (await response.json()) as { id: number; html_url: string }
+
+  return {
+    success: true,
+    commentId: data.id,
+    url: data.html_url,
+  }
+}
+
+// ── Usage example ──────────────────────────────────────────────────────────
+
+const config: PRCommentConfig = {
+  owner: 'acme-corp',
+  repo: 'platform-api',
+  prNumber: 42,
+  token: process.env.GITHUB_TOKEN || 'ghp_your_personal_access_token',
+}
+
+const issues: DocumentationIssue[] = [
+  {
+    file: 'src/auth/login.ts',
+    line: 14,
+    message: 'Missing JSDoc for exported function `loginUser`',
+    severity: 'error',
+  },
+  {
+    file: 'src/utils/format.ts',
+    line: 88,
+    message: '`@param` description is empty',
+    severity: 'warning',
+  },
+  {
+    file: 'README.md',
+    message: 'No usage examples found in README',
+    severity: 'warning',
+  },
+]
+
+async function main() {
+  try {
+    const result = await postPRComment(config, issues)
+
+    console.log('Comment posted successfully!')
+    console.log('Comment ID:', result.commentId)
+    console.log('View it at:', result.url)
+    // Expected output:
+    // Comment posted successfully!
+    // Comment ID: 1987654321
+    // View it at: https://github.com/acme-corp/platform-api/pull/42#issuecomment-1987654321
+  } catch (error) {
+    console.error('Failed to post PR comment:', error)
+    // Common causes:
+    //   - Invalid or expired GITHUB_TOKEN
+    //   - Bot lacks write access to the repository
+    //   - PR number does not exist
+  }
+}
+
+main()
+```
+
+### `postInlineComments`
+
+```typescript
+async function postInlineComments(config: PRCommentConfig, issues: DocumentationIssue[]): Promise<CommentResult[]>
+```
+
+Use this to post inline review comments on specific lines of a pull request, flagging documentation issues directly in the GitHub code review interface.
+
+This function iterates over a list of documentation issues and attaches each as an inline comment to the relevant file and line in a PR — ideal for automated doc linters, CI checks, or code review bots.
+
+#### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `config` | `PRCommentConfig` | Yes | PR targeting config including `token`, `owner`, `repo`, `pullNumber`, and `commitSha` |
+| `issues` | `DocumentationIssue[]` | Yes | Array of documentation issues, each with a `file`, `line`, and `message` to post as an inline comment |
+
+#### Returns
+
+**`Promise<CommentResult[]>`** — Resolves to an array of results, one per issue. Each `CommentResult` contains:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `success` | `boolean` | Whether the comment was posted successfully |
+| `commentId` | `number \| undefined` | GitHub comment ID if successful |
+| `error` | `string \| undefined` | Error message if the post failed |
+
+Returns an empty array if `issues` is empty. Individual entries may have `success: false` if a specific comment failed (e.g., invalid line number or file path), without aborting the rest.
+
+**Example:**
+
+```typescript example.ts
+// ── Inline type definitions (no external imports needed) ──────────────────────
+
+type PRCommentConfig = {
+  token?: string
+  owner: string
+  repo: string
+  pullNumber: number
+  commitSha: string
+}
+
+type DocumentationIssue = {
+  file: string
+  line: number
+  message: string
+}
+
+type CommentResult = {
+  success: boolean
+  commentId?: number
+  error?: string
+}
+
+// ── Simulated implementation of postInlineComments ───────────────────────────
+
+async function postInlineComments(
+  config: PRCommentConfig,
+  issues: DocumentationIssue[]
+): Promise<CommentResult[]> {
+  const token = config.token || process.env.GITHUB_TOKEN
+
+  if (!token) {
+    throw new Error('GitHub token is required (set GITHUB_TOKEN or pass config.token)')
+  }
+
+  const results: CommentResult[] = []
+
+  for (const issue of issues) {
+    try {
+      // Simulate a GitHub API call to POST /repos/{owner}/{repo}/pulls/{pull_number}/comments
+      const apiUrl = `https://api.github.com/repos/${config.owner}/${config.repo}/pulls/${config.pullNumber}/comments`
+
+      console.log(`[POST] ${apiUrl}`)
+      console.log(`  → File: ${issue.file}, Line: ${issue.line}`)
+      console.log(`  → Comment: "${issue.message}"`)
+
+      // Simulate a successful response (replace with real fetch in production)
+      const simulatedResponse = {
+        id: Math.floor(Math.random() * 900000) + 100000,
+        body: issue.message,
+        path: issue.file,
+        line: issue.line,
+      }
+
+      results.push({
+        success: true,
+        commentId: simulatedResponse.id,
+      })
+    } catch (err) {
+      results.push({
+        success: false,
+        error: err instanceof Error ? err.message : String(err),
+      })
+    }
+  }
+
+  return results
+}
+
+// ── Example usage ─────────────────────────────────────────────────────────────
+
+const prConfig: PRCommentConfig = {
+  token: process.env.GITHUB_TOKEN || 'ghp_your_token_here',
+  owner: 'acme-corp',
+  repo: 'backend-api',
+  pullNumber: 42,
+  commitSha: 'a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2',
+}
+
+const documentationIssues: DocumentationIssue[] = [
+  {
+    file: 'src/auth/login.ts',
+    line: 18,
+    message: 'Missing JSDoc comment for exported function `validateToken`.',
+  },
+  {
+    file: 'src/utils/format.ts',
+    line: 45,
+    message: '`@param` description is empty for parameter `options`.',
+  },
+  {
+    file: 'src/models/user.ts',
+    line: 72,
+    message: 'Exported interface `UserProfile` has no documentation block.',
+  },
+]
+
+async function main() {
+  try {
+    console.log(`Posting ${documentationIssues.length} inline comment(s) to PR #${prConfig.pullNumber}...\n`)
+
+    const results = await postInlineComments(prConfig, documentationIssues)
+
+    results.forEach((result, index) => {
+      const issue = documentationIssues[index]
+      if (result.success) {
+        console.log(`✅ Comment posted on ${issue.file}:${issue.line} (ID: ${result.commentId})`)
+      } else {
+        console.error(`❌ Failed on ${issue.file}:${issue.line} — ${result.error}`)
+      }
+    })
+
+    const successCount = results.filter(r => r.success).length
+    console.log(`\nSummary: ${successCount}/${results.length} comments posted successfully.`)
+
+    // Expected output:
+    // Posting 3 inline comment(s) to PR #42...
+    //
+    // [POST] https://api.github.com/repos/acme-corp/backend-api/pulls/42/comments
+    //   → File: src/auth/login.ts, Line: 18
+    //   → Comment: "Missing JSDoc comment for exported function `validateToken`."
+    // ✅ Comment posted on src/auth/login.ts:18 (ID: 583921)
+    // ... (repeated for each issue)
+    // Summary: 3/3 comments posted successfully.
+  } catch (error) {
+    console.error('Fatal error posting inline comments:', error)
+    process.exit(1)
+  }
+}
+
+main()
+```
+
+### `analyzePRForDocs`
+
+```typescript
+async function analyzePRForDocs(config: PRCommentConfig, _options: { checkExamples?: boolean } = {}): Promise<DocumentationIssue[]>
+```
+
+Use this to scan a pull request for documentation issues — missing docstrings, undocumented parameters, or incomplete return type descriptions — and get a structured list of problems to act on.
+
+Accepts a `PRCommentConfig` object describing the GitHub PR to analyze, plus optional flags to control analysis depth. Returns a list of `DocumentationIssue` objects, each describing a specific documentation problem found in the PR's changed files.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `config` | `PRCommentConfig` | Yes | GitHub PR connection details including repo owner, repo name, PR number, and auth token |
+| `config.token` | `string` | No | GitHub personal access token. Falls back to `GITHUB_TOKEN` environment variable |
+| `config.owner` | `string` | Yes | GitHub repository owner (user or org) |
+| `config.repo` | `string` | Yes | Repository name |
+| `config.prNumber` | `number` | Yes | Pull request number to analyze |
+| `_options` | `object` | No | Additional analysis options |
+| `_options.checkExamples` | `boolean` | No | When `true`, also validates that code examples in docstrings are present and well-formed |
+
+#### Returns
+
+`Promise<DocumentationIssue[]>` — Resolves to an array of documentation issues found in the PR. Each issue describes the file, location, and nature of the documentation problem. Returns an empty array if no issues are found.
+
+**Example:**
+
+```typescript example.ts
+// --- Inline types (do not import from autodocs) ---
+type PRCommentConfig = {
+  token?: string
+  owner: string
+  repo: string
+  prNumber: number
+}
+
+type DocumentationIssue = {
+  file: string
+  line: number
+  severity: 'error' | 'warning' | 'info'
+  message: string
+  rule: string
+}
+
+// --- Simulated implementation of analyzePRForDocs ---
+async function analyzePRForDocs(
+  config: PRCommentConfig,
+  _options: { checkExamples?: boolean } = {}
+): Promise<DocumentationIssue[]> {
+  const token = config.token || process.env.GITHUB_TOKEN
+
+  if (!token) {
+    throw new Error(
+      'GitHub token is required. Set GITHUB_TOKEN env var or pass config.token.'
+    )
+  }
+
+  // Simulate fetching PR diff and analyzing changed files
+  console.log(
+    `Analyzing PR #${config.prNumber} in ${config.owner}/${config.repo}...`
+  )
+
+  // Simulated issues found in the PR
+  const issues: DocumentationIssue[] = [
+    {
+      file: 'src/payments/charge.ts',
+      line: 14,
+      severity: 'error',
+      message: 'Exported function `chargeCustomer` is missing a docstring.',
+      rule: 'require-jsdoc',
+    },
+    {
+      file: 'src/payments/charge.ts',
+      line: 14,
+      severity: 'warning',
+      message: 'Parameter `amount` is not documented.',
+      rule: 'require-param-docs',
+    },
+    {
+      file: 'src/utils/format.ts',
+      line: 42,
+      severity: 'warning',
+      message: 'Return type for `formatCurrency` is not documented.',
+      rule: 'require-returns-docs',
+    },
+  ]
+
+  if (_options.checkExamples) {
+    issues.push({
+      file: 'src/payments/charge.ts',
+      line: 14,
+      severity: 'info',
+      message: 'No usage example found in docstring for `chargeCustomer`.',
+      rule: 'require-example',
+    })
+  }
+
+  return issues
+}
+
+// --- Usage ---
+async function main() {
+  try {
+    const issues = await analyzePRForDocs(
+      {
+        token: process.env.GITHUB_TOKEN || 'ghp_your_token_here',
+        owner: 'acme-corp',
+        repo: 'payments-service',
+        prNumber: 247,
+      },
+      { checkExamples: true }
+    )
+
+    if (issues.length === 0) {
+      console.log('✅ No documentation issues found.')
+      return
+    }
+
+    console.log(`Found ${issues.length} documentation issue(s):\n`)
+
+    for (const issue of issues) {
+      const icon = issue.severity === 'error' ? '❌' : issue.severity === 'warning' ? '⚠️' : 'ℹ️'
+      console.log(`${icon} [${issue.severity.toUpperCase()}] ${issue.file}:${issue.line}`)
+      console.log(`   ${issue.message}`)
+      console.log(`   Rule: ${issue.rule}\n`)
+    }
+
+    // Expected output:
+    // Found 4 documentation issue(s):
+    //
+    // ❌ [ERROR] src/payments/charge.ts:14
+    //    Exported function `chargeCustomer` is missing a docstring.
+    //    Rule: require-jsdoc
+    //
+    // ⚠️ [WARNING] src/payments/charge.ts:14
+    //    Parameter `amount` is not documented.
+    //    Rule: require-param-docs
+    // ...
+  } catch (error) {
+    console.error('Analysis failed:', error instanceof Error ? error.message : error)
+    process.exit(1)
+  }
+}
+
+main()
+```
+