### Run Onboarding Script

Source: https://github.com/anivar/contributor-codebase-analyzer/blob/main/references/onboarding.md

Executes the automated onboarding process for the contributor-codebase-analyzer. This script handles platform detection, configuration, and prerequisite verification.

```bash
./scripts/checkpoint.sh onboard

```

--------------------------------

### Manually Install Contributor Codebase Analyzer

Source: https://context7.com/anivar/contributor-codebase-analyzer/llms.txt

Provides instructions for manually installing the Contributor Codebase Analyzer by cloning the repository and creating a symbolic link. This method is useful for development or specific environment setups.

```bash
git clone https://github.com/anivar/contributor-codebase-analyzer.git
ln -s "$(pwd)/contributor-codebase-analyzer" ~/.agents/skills/contributor-codebase-analyzer
```

--------------------------------

### Add First Contributor (Optional)

Source: https://github.com/anivar/contributor-codebase-analyzer/blob/main/references/onboarding.md

Provides steps to optionally add the first contributor by discovering their username and then finding their associated email addresses from the Git log.

```bash
# Discover contributors from git log (top 10 by commit count)
echo "Top contributors in this repo:"
git shortlog -sn --all | head -10

# To add a contributor:
# Provide their GitHub/GitLab username
# The skill auto-discovers their email variants from git log

# Example: add github.com/alice-dev
USERNAME="alice-dev"
mkdir -p "$PROJECT/.cca/contributors/@$USERNAME"

# Discover their git email(s)
git log --all --format='%ae %an' | sort -u | grep -i "$USERNAME"

```

--------------------------------

### CCA Configuration File Example

Source: https://github.com/anivar/contributor-codebase-analyzer/blob/main/AGENTS.md

An example of the .cca-config.json file, showing various configuration options for the contributor codebase analyzer, including platform, repository details, tracked contributors, and path exclusions.

```json
{
  "platform": "github",
  "cli_tool": "gh",
  "repo": "org/repo-name",
  "org": "org-name",
  "created_at": "2025-01-15T10:00:00Z",
  "contributors_tracked": ["@alice", "@bob"],
  "default_branch": "main",
  "critical_paths": ["src/modules/payment", "src/modules/orders"],
  "excluded_paths": ["__tests__", "docs/", "*.md"]
}
```

--------------------------------

### Verify Onboarding Status

Source: https://github.com/anivar/contributor-codebase-analyzer/blob/main/references/onboarding.md

Runs a checkpoint status command to verify that the onboarding process has been completed successfully and displays the initial analyzer status.

```bash
./scripts/checkpoint.sh status

```

--------------------------------

### JSONL Schema and Data Example

Source: https://github.com/anivar/contributor-codebase-analyzer/blob/main/AGENTS.md

Demonstrates the schema declaration and subsequent data entries in a JSON Lines (.jsonl) file, commonly used for contributor profiles.

```jsonl
{"_schema":"contributor-profile","fields":["type","timestamp","period","data"]}
{"type":"metrics","timestamp":"2025-01-15T10:30:00Z","period":"2025","data":{"commits":413,"prs":89}}
{"type":"accuracy","timestamp":"2025-01-15T11:00:00Z","period":"2025","data":{"accuracy_rate":77.97}}
```

--------------------------------

### Self-Hosted GitHub Enterprise Authentication

Source: https://github.com/anivar/contributor-codebase-analyzer/blob/main/references/onboarding.md

Demonstrates how to authenticate with a self-hosted GitHub Enterprise instance using the GitHub CLI by specifying the hostname during the login process.

```bash
# GitHub Enterprise
gh auth login --hostname github.yourcompany.com

```

--------------------------------

### Install Contributor Codebase Analyzer Globally

Source: https://context7.com/anivar/contributor-codebase-analyzer/llms.txt

Installs the Contributor Codebase Analyzer skill globally for all AI agents using npm. This is the primary method for making the skill available.

```bash
npx skills add anivar/contributor-codebase-analyzer -g
```

--------------------------------

### Create CCA Configuration File

Source: https://github.com/anivar/contributor-codebase-analyzer/blob/main/references/onboarding.md

Generates the `.cca-config.json` file within the project's `.cca` directory. This file stores essential configuration details like platform, repository, and default branch.

```bash
mkdir -p "$PROJECT/.cca"/{contributors,codebase,governance}

cat > "$PROJECT/.cca/.cca-config.json" <<EOF
{
  "platform": "$PLATFORM",
  "cli_tool": "$CLI_TOOL",
  "repo": "$ORG/$REPO_NAME",
  "org": "$ORG",
  "created_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
  "contributors_tracked": [],
  "default_branch": "$DEFAULT_BRANCH",
  "critical_paths": [],
  "excluded_paths": ["__tests__", "*.test.*", "docs/", "*.md"]
}
EOF

```

--------------------------------

### Verify Prerequisite CLI Tools

Source: https://github.com/anivar/contributor-codebase-analyzer/blob/main/references/onboarding.md

Checks for the presence and authentication status of essential command-line tools like Git, GitHub CLI (gh), and GitLab CLI (glab). It also warns if optional tools like jq or bc are missing.

```bash
# Check git
git --version || echo "ERROR: git is required"

# Check platform CLI
if [ "$PLATFORM" = "github" ]; then
    gh --version 2>/dev/null || echo "WARNING: gh (GitHub CLI) not installed. PR/MR counts will be unavailable."
    gh auth status 2>/dev/null || echo "WARNING: gh not authenticated. Run: gh auth login"
elif [ "$PLATFORM" = "gitlab" ]; then
    glab --version 2>/dev/null || echo "WARNING: glab (GitLab CLI) not installed. MR counts will be unavailable."
    glab auth status 2>/dev/null || echo "WARNING: glab not authenticated. Run: glab auth login"
fi

# Check optional tools
jq --version 2>/dev/null || echo "NOTE: jq not installed. JSON parsing will use fallback methods."
bc --version 2>/dev/null || echo "NOTE: bc not installed. Accuracy calculations will use awk."

```

--------------------------------

### Extract Repository and Organization/Group

Source: https://github.com/anivar/contributor-codebase-analyzer/blob/main/references/onboarding.md

Parses the Git remote URL to extract the repository path, organization/group name, and repository name. This is crucial for configuring the analyzer.

```bash
# Parse org/repo from remote URL
# Handles: git@github.com:org/repo.git, https://github.com/org/repo.git
REPO_PATH=$(echo "$REMOTE_URL" | sed -E 's|.*[:/]([^/]+/[^/]+?)(\.git)?$|\1|')
ORG=$(echo "$REPO_PATH" | cut -d'/' -f1)
REPO_NAME=$(echo "$REPO_PATH" | cut -d'/' -f2)

echo "Org/Group: $ORG"
echo "Repo: $REPO_NAME"
echo "Full path: $ORG/$REPO_NAME"

```

--------------------------------

### JSONL Schema Declaration and Data Entry Example

Source: https://github.com/anivar/contributor-codebase-analyzer/blob/main/references/periodic-saving.md

Demonstrates the schema-first pattern for JSONL files, where the first line defines the schema, followed by data entries. This format is used for storing contributor profiles and analysis results.

```jsonl
{"_schema":"contributor-profile","fields":["type","timestamp","period","data"]}
{"type":"metrics","timestamp":"2025-01-15T10:30:00Z","period":"2025","data":{"commits":413,"prs":89,"reviews":42,"lines_added":45000,"lines_removed":12000}}
{"type":"accuracy","timestamp":"2025-01-15T11:00:00Z","period":"2025","data":{"total_commits":413,"fix_related":91,"accuracy_rate":77.97,"self_reverts":3,"same_day_fixes":42}}
{"type":"quality","timestamp":"2025-01-15T11:30:00Z","period":"2025-Q1","data":{"anti_patterns":{"debug_code":3,"empty_catch":1},"strengths":{"defensive_programming":12,"code_reduction":5}}}
{"type":"review","timestamp":"2025-01-15T12:00:00Z","period":"2025","data":{"level":"Exceeds Expectations","recommendation":"PROMOTE_WITH_GROWTH_PLAN","file":"latest-review.md"}}
```

--------------------------------

### Detect Git Platform and CLI Tool

Source: https://github.com/anivar/contributor-codebase-analyzer/blob/main/references/onboarding.md

Identifies the Git platform (GitHub or GitLab) and the corresponding command-line interface (CLI) tool by parsing the remote URL. It includes logic to detect self-hosted GitLab instances.

```bash
# Read the remote URL
REMOTE_URL=$(git remote get-url origin 2>/dev/null)

# Detect platform
if echo "$REMOTE_URL" | grep -qiE "github\.com|github\."; then
    PLATFORM="github"
    CLI_TOOL="gh"
elif echo "$REMOTE_URL" | grep -qiE "gitlab\.com|gitlab\."; then
    PLATFORM="gitlab"
    CLI_TOOL="glab"
else
    # Could be self-hosted — check for GitLab API markers
    DOMAIN=$(echo "$REMOTE_URL" | sed -E 's|.*[@/]([^:/]+)[:/].*|\1|')
    if curl -s "https://$DOMAIN/api/v4/version" 2>/dev/null | grep -q "version"; then
        PLATFORM="gitlab"
        CLI_TOOL="glab"
    else
        PLATFORM="github"
        CLI_TOOL="gh"
    fi
fi

echo "Detected platform: $PLATFORM (CLI: $CLI_TOOL)"

```

--------------------------------

### Configure GitLab Self-Hosted Host

Source: https://github.com/anivar/contributor-codebase-analyzer/blob/main/references/onboarding.md

Set the GITLAB_HOST environment variable to specify your self-hosted GitLab instance. This allows the glab CLI to connect to your private GitLab server. Ensure the hostname is correctly entered.

```bash
export GITLAB_HOST=gitlab.yourcompany.com
glab auth login --hostname gitlab.yourcompany.com
```

--------------------------------

### Diff Content Boundary Markers

Source: https://github.com/anivar/contributor-codebase-analyzer/blob/main/AGENTS.md

Illustrates the use of explicit boundary markers when presenting diff content to an analysis context. This practice helps distinguish untrusted diff data from other content, mitigating risks like prompt injection. The format includes a start marker, the diff content, and an end marker, along with a unique identifier (SHA).

```text
---
BEGIN UNTRUSTED DIFF [SHA] ---
[diff content here]
--- END UNTRUSTED DIFF [SHA] ---
```

--------------------------------

### Find Entry Points in Repository

Source: https://context7.com/anivar/contributor-codebase-analyzer/llms.txt

Locates files commonly used as entry points for applications or modules, such as `index.ts`, `index.tsx`, `main.ts`, or `App.tsx`. This is useful for understanding the application's starting points and structure. It uses the `find` command with multiple name patterns.

```bash
find . -name "index.ts" -o -name "index.tsx" -o -name "main.ts" \
  -o -name "App.tsx" | head -10
```

--------------------------------

### Detect Default Git Branch

Source: https://github.com/anivar/contributor-codebase-analyzer/blob/main/references/onboarding.md

Determines the default branch of the Git repository by checking common branch names like 'main', 'master', 'production', 'prod', and 'release'.

```bash
DEFAULT_BRANCH="main"
for branch in main master production prod release; do
    if git rev-parse --verify "origin/$branch" >/dev/null 2>&1;
        DEFAULT_BRANCH="$branch"
        break
    fi
done
echo "Default branch: $DEFAULT_BRANCH"

```

--------------------------------

### Find Entry Point Files (Bash)

Source: https://github.com/anivar/contributor-codebase-analyzer/blob/main/AGENTS.md

This bash command searches for files named 'index.ts', 'index.tsx', 'main.ts', or 'main.tsx' within the current directory and its subdirectories. These files often serve as the entry points for modules or the application. The output is limited to the first 20 found files.

```bash
# Entry points
find . -name "index.ts" -o -name "index.tsx" -o -name "main.ts" | head -20
```

--------------------------------

### Extract Dependencies from package.json (Bash/jq)

Source: https://github.com/anivar/contributor-codebase-analyzer/blob/main/AGENTS.md

This command uses 'cat' to read the 'package.json' file and 'jq' to extract the 'dependencies' and 'devDependencies' sections. This is useful for understanding the project's external library dependencies.

```bash
# Dependencies
cat package.json | jq '.dependencies, .devDependencies'
```

--------------------------------

### List GitHub Repositories with Details (Bash/gh CLI)

Source: https://github.com/anivar/contributor-codebase-analyzer/blob/main/AGENTS.md

This command uses the GitHub CLI ('gh') to list repositories for a given organization. It fetches the repository name, primary language, and last updated timestamp, limiting the results to 100 repositories. This is part of analyzing cross-repo relationships.

```bash
# List org repos
# GitHub:
gh repo list ORG --limit 100 --json name,language,updatedAt
```

--------------------------------

### Extract Direct Dependencies from package.json

Source: https://github.com/anivar/contributor-codebase-analyzer/blob/main/references/codebase-analysis.md

This bash script uses `cat` and `jq` to parse the `package.json` file and extract the names of direct dependencies. It handles cases where `package.json` might not exist or `jq` is not installed by redirecting errors.

```bash
cat package.json | jq -r '.dependencies | keys[]' 2>/dev/null | sort
```

--------------------------------

### Format of .last_analyzed File

Source: https://github.com/anivar/contributor-codebase-analyzer/blob/main/AGENTS.md

Specifies the content of the .last_analyzed file, which includes an ISO 8601 timestamp on the first line and the last analyzed Git SHA on the second line.

```text
2025-01-15T12:00:00Z
abc1234def5678
```

--------------------------------

### Contributor Profile Update JSONL Example

Source: https://github.com/anivar/contributor-codebase-analyzer/blob/main/references/accuracy-analysis.md

This JSONL snippet demonstrates how to append accuracy analysis results to a contributor's profile. It includes metrics like total commits, fix-related commits, accuracy rate, and specific bug indicators for a given period.

```json
{"type":"accuracy","timestamp":"2025-01-15T10:30:00Z","period":"2025","total_commits":413,"fix_related":91,"accuracy_rate":77.97,"self_reverts":3,"reverted_by_others":0,"same_day_fixes":42,"crash_fixes":15,"hook_bypass":2,"console_cleanup":29}
```

--------------------------------

### List GitLab Projects with Subgroups

Source: https://github.com/anivar/contributor-codebase-analyzer/blob/main/AGENTS.md

Lists projects within a GitLab group, including those in nested subgroups. It uses the 'glab' CLI and outputs the results in JSON format for further processing. The '--per-page' flag controls the number of items returned per request.

```bash
glab project list --group GROUP --include-subgroups --per-page 100 -o json
```

--------------------------------

### Find Tech Debt Markers in Code

Source: https://github.com/anivar/contributor-codebase-analyzer/blob/main/AGENTS.md

Searches the current directory and its subdirectories for files containing common technical debt markers like 'TODO', 'FIXME', 'HACK', or 'XXX'. It counts the number of files that contain at least one of these markers.

```bash
find . -type f ( -name "*.ts" -o -name "*.tsx" -o -name "*.js" ) -exec \
  grep -l "TODO\|FIXME\|HACK\|XXX" {} \; | wc -l
```

--------------------------------

### Resume Protocol: Checking for New Commits (Bash)

Source: https://github.com/anivar/contributor-codebase-analyzer/blob/main/AGENTS.md

A bash script snippet that checks if a contributor's analysis is up-to-date by comparing the last analyzed SHA with the current HEAD. It calculates and reports the number of new commits.

```bash
if [ -f "$PROJECT/.cca/contributors/@username/.last_analyzed" ]; then
    LAST_SHA=$(tail -1 "$PROJECT/.cca/contributors/@username/.last_analyzed")
    NEW_COMMITS=$(git log --author="EMAIL" "$LAST_SHA"..HEAD --oneline | wc -l)
    if [ "$NEW_COMMITS" -eq 0 ]; then
        echo "Analysis is current — no new commits"
    else
        echo "Resuming from $LAST_SHA — $NEW_COMMITS new commits"
    fi
fi
```

--------------------------------

### Bash: List Outdated npm Dependencies

Source: https://github.com/anivar/contributor-codebase-analyzer/blob/main/references/codebase-analysis.md

This command uses `npm outdated` with the `--json` flag to get a list of dependencies that have newer versions available. It then uses `jq` to format the output, showing the package name and the current vs. latest version.

```bash
# Outdated dependencies
npm outdated --json 2>/dev/null | jq 'to_entries[] |
  select(.value.current != .value.latest) |
  "\(.key): \(.value.current) → \(.value.latest)"'
```

--------------------------------

### Get Security Vulnerability Summary using npm audit

Source: https://context7.com/anivar/contributor-codebase-analyzer/llms.txt

This command retrieves a summary of security vulnerabilities (critical, high, moderate, low) from the `npm audit` output. It pipes the JSON output to `jq` to extract the vulnerability counts from the metadata. Errors are redirected to `/dev/null` to suppress them.

```bash
npm audit --json 2>/dev/null | jq '.metadata.vulnerabilities'
```

--------------------------------

### Querying Contributor Analysis State

Source: https://github.com/anivar/contributor-codebase-analyzer/blob/main/references/periodic-saving.md

This set of commands demonstrates how to query saved analysis state for contributors. It includes retrieving the latest accuracy rate, listing all tracked contributors, getting the last analysis time for the codebase, and counting the total number of analysis runs for a specific contributor.

```bash
# Get latest accuracy for a contributor
tail -n +2 "$PROJECT/.cca/contributors/@alice/profile.jsonl" | \
  grep '"type":"accuracy"' | tail -1 | jq '.data.accuracy_rate'

# List all tracked contributors
ls "$PROJECT/.cca/contributors/"

# Get last analysis time for codebase
cat "$PROJECT/.cca/codebase/.last_analyzed"

# Count total analysis runs for a contributor
wc -l < "$PROJECT/.cca/contributors/@alice/profile.jsonl"
# (subtract 1 for schema line)
```

--------------------------------

### Onboard Contributor Codebase Analyzer

Source: https://github.com/anivar/contributor-codebase-analyzer/blob/main/SKILL.md

Initiates the onboarding process for the Contributor Codebase Analyzer. This script detects the git platform, identifies the repository and organization, creates the necessary configuration directory, verifies CLI tool availability, and optionally adds the first contributor to track. It serves as the initial setup for first-time users.

```bash
./scripts/checkpoint.sh onboard
```

--------------------------------

### List Merged MRs (GitLab CLI)

Source: https://github.com/anivar/contributor-codebase-analyzer/blob/main/AGENTS.md

Lists merged merge requests for a specific author on GitLab using the 'glab' CLI and pipes the output to 'jq' to count the results. Requires 'glab' and 'jq' to be installed.

```bash
glab mr list --author=USERNAME --state=merged --per-page=100 -o json | jq length
```

--------------------------------

### JSON Structure for Saving Quality Findings

Source: https://github.com/anivar/contributor-codebase-analyzer/blob/main/references/code-quality-catalog.md

Example JSON structure for saving quarterly quality findings, including counts of anti-patterns and strengths, and the relevant period.

```json
{
  "type": "quality",
  "timestamp": "2025-01-15T10:30:00Z",
  "period": "2025-Q1",
  "anti_patterns": {
    "debug_code": 3,
    "empty_catch": 1,
    "hook_bypass": 0
  },
  "strengths": {
    "defensive_programming": 12,
    "code_reduction": 5,
    "offline_first": 3
  }
}
```

--------------------------------

### Calculate Quarterly Commits (Bash)

Source: https://github.com/anivar/contributor-codebase-analyzer/blob/main/AGENTS.md

Bash script to count commits for a given author within each quarter of a year. This is used for batch sizing analysis.

```bash
for q in "01-01 04-01" "04-01 07-01" "07-01 10-01" "10-01 NEXTYEAR-01-01"; do
    START=$(echo $q | cut -d' ' -f1)
    END=$(echo $q | cut -d' ' -f2)
    COUNT=$(git log --author="EMAIL" --after="YEAR-$START" --before="YEAR-$END" --oneline | wc -l)
    echo "Q: $COUNT commits"
done
```

--------------------------------

### Calculate Adjusted Commit Volume

Source: https://github.com/anivar/contributor-codebase-analyzer/blob/main/references/code-quality-catalog.md

Formula to adjust raw commit count by subtracting fix-related commits, cleanup, and reverts to get a more accurate measure of effective commits.

```text
Adjusted Volume = Total commits - fix-related - cleanup - reverts
```

--------------------------------

### Calculate Monthly Commit Breakdown

Source: https://github.com/anivar/contributor-codebase-analyzer/blob/main/references/contributor-analysis.md

Iterates through each month of a given year to count the number of commits made by a specific author. It dynamically calculates the start and end dates for each month.

```bash
# Monthly breakdown
for month in $(seq -w 1 12); do
    NEXT_MONTH=$((10#$month + 1))
    NEXT_YEAR=$YEAR
    if [ "$NEXT_MONTH" -gt 12 ]; then NEXT_MONTH=1; NEXT_YEAR=$((YEAR+1)); fi
    NEXT_MONTH=$(printf "%02d" $NEXT_MONTH)
    COUNT=$(git log --author="EMAIL" \
      --after="$YEAR-$month-01" --before="$NEXT_YEAR-$NEXT_MONTH-01" --oneline | wc -l)
    echo "Month $month: $COUNT commits"
done
```

--------------------------------

### Get Production Source Files using Git

Source: https://context7.com/anivar/contributor-codebase-analyzer/llms.txt

This command uses `git ls-files` to list all tracked files in the repository and then filters them to identify production source files. It excludes test files, documentation, and configuration files, focusing on `.ts`, `.tsx`, `.js`, and `.jsx` files. The output is a list of production file paths.

```bash
# Get production source files (exclude tests, docs, configs)
git ls-files | \
    grep -v -E "__tests__|\.test\.|.spec\.|test/" | \
    grep -v -E "\.md$|docs/|README" | \
    grep -E "\.(ts|tsx|js|jsx)$" > /tmp/production_files.txt
```

--------------------------------

### Directory Structure of CCA Project

Source: https://github.com/anivar/contributor-codebase-analyzer/blob/main/AGENTS.md

Illustrates the hierarchical organization of the .cca directory, including subdirectories for contributors, codebase, and governance, along with configuration and data files.

```bash
$PROJECT/.cca/
├── contributors/
│   └── @username/
│       ├── profile.jsonl             # Append-only: one JSON object per analysis run
│       ├── checkpoints/
│       │   ├── 2025-Q1.md           # Quarterly findings snapshot
│       │   └── 2025-Q2.md
│       ├── latest-review.md          # Most recent annual review
│       └── .last_analyzed            # ISO timestamp + last SHA analyzed
├── codebase/
│   ├── structure.json                # Current repo structure
│   ├── dependencies.json             # Dependency catalog
│   └── .last_analyzed
governance/
│   ├── portfolio.json                # Technology portfolio
│   ├── debt-registry.json            # Technical debt items
│   ├── security-audit.json           # Last security findings
│   └── .last_analyzed
└── .cca-config.json        # Skill configuration
```

--------------------------------

### Find Entry Point Files in Repository

Source: https://github.com/anivar/contributor-codebase-analyzer/blob/main/references/codebase-analysis.md

This bash script locates common entry point files for applications within a repository, such as `index.ts`, `main.ts`, `App.tsx`, and `app.ts`. It uses `find` to search for these specific filenames and limits the output to the first 20 found.

```bash
find . -name "index.ts" -o -name "index.tsx" -o -name "main.ts" \
  -o -name "App.tsx" -o -name "app.ts" | head -20
```

--------------------------------

### Calculate Adjusted Volume (Conceptual)

Source: https://github.com/anivar/contributor-codebase-analyzer/blob/main/AGENTS.md

This is a conceptual representation of how adjusted volume might be calculated by subtracting specific types of commits from the total. It's not executable code but a formula.

```text
Adjusted Volume = Total - fix-related - cleanup - reverts
```

--------------------------------

### Checkpoint Saving Protocol using Bash

Source: https://github.com/anivar/contributor-codebase-analyzer/blob/main/references/periodic-saving.md

Illustrates the bash commands used to save checkpoints after different analysis phases. This includes appending metrics to JSONL files, copying markdown snapshots, and updating the .last_analyzed file with timestamp and git SHA.

```bash
# After contributor Phase 2 (metrics gathered)
echo '{"type":"metrics","timestamp":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","period":"2025","data":{...}}' \
  >> "$PROJECT/.cca/contributors/@username/profile.jsonl"

# After contributor Phase 3 (diffs read for a quarter)
cp SCRATCHPAD/username-Q1-findings.md \
  "$PROJECT/.cca/contributors/@username/checkpoints/2025-Q1.md"

# After contributor Phase 6 (report generated)
cp OUTPUT/username-2025-review.md \
  "$PROJECT/.cca/contributors/@username/latest-review.md"

# Update last analyzed
echo "$(date -u +%Y-%m-%dT%H:%M:%SZ)" > "$PROJECT/.cca/contributors/@username/.last_analyzed"
git log --author="EMAIL" -1 --format="%H" >> "$PROJECT/.cca/contributors/@username/.last_analyzed"
```

--------------------------------

### Phase 2: Gather Commit Metrics (Bash)

Source: https://github.com/anivar/contributor-codebase-analyzer/blob/main/AGENTS.md

Bash commands to count the total number of commits for a specific author within a year and to break down commit counts by month.

```bash
# Commits
git log --author="EMAIL" --after="YEAR-01-01" --before="YEAR+1-01-01" --oneline | wc -l

# Monthly breakdown
for month in $(seq -w 1 12); do
    git log --author="EMAIL" --after="YEAR-$month-01" --before="YEAR-$((month+1))-01" --oneline | wc -l
done
```

--------------------------------

### Bash: Extract Framework Versions from package.json

Source: https://github.com/anivar/contributor-codebase-analyzer/blob/main/references/codebase-analysis.md

This script loops through repositories, fetches their `package.json` file, and extracts dependency versions for common frontend frameworks like React, Angular, Vue, and backend frameworks like Express. It filters for specific framework keys and outputs them with their versions.

```bash
# Framework versions
for repo in $(gh repo list ORG --limit 50 --json name --jq '.[].name'); do
    echo "=== $repo ==="
    gh api "repos/ORG/$repo/contents/package.json" --jq '.content' 2>/dev/null | \
      base64 -d 2>/dev/null | jq -r '.dependencies | to_entries[] |
      select(.key | test("react|angular|vue|next|express|fastify")) |
      "\(.key): \(.value)"' 2>/dev/null
done
```

--------------------------------

### Configuration File for Contributor Codebase Analyzer

Source: https://github.com/anivar/contributor-codebase-analyzer/blob/main/references/periodic-saving.md

This JSON configuration file defines various parameters for the contributor codebase analyzer. It includes repository details, tracked contributors, default branch, critical paths to focus on, and paths to exclude from analysis.

```json
{
  "repo": "org/repo-name",
  "org": "org-name",
  "created_at": "2025-01-15T10:00:00Z",
  "contributors_tracked": ["@alice", "@bob", "@charlie"],
  "default_branch": "main",
  "critical_paths": [
    "src/modules/payment",
    "src/modules/orders",
    "src/modules/auth"
  ],
  "excluded_paths": [
    "__tests__",
    "*.test.*",
    "docs/",
    "*.md"
  ]
}
```

--------------------------------

### Check Analysis Status

Source: https://context7.com/anivar/contributor-codebase-analyzer/llms.txt

Determines if code analysis is needed for a contributor by checking the current analysis status. It returns 'FRESH', 'CURRENT', or 'INCREMENTAL' to guide whether a full, skipped, or partial analysis should be performed.

```bash
./scripts/checkpoint.sh check contributors/@alice --author alice@example.com
```

--------------------------------

### List Project Dependencies from package.json

Source: https://context7.com/anivar/contributor-codebase-analyzer/llms.txt

Extracts and sorts the names of production dependencies listed in the `package.json` file. This provides a quick overview of the external libraries the project relies on. It uses `cat` to read the file and `jq` to parse the JSON output.

```bash
cat package.json | jq -r '.dependencies | keys[]' | sort | head -10
```

--------------------------------

### List GitHub Repositories (GitHub CLI)

Source: https://github.com/anivar/contributor-codebase-analyzer/blob/main/SKILL.md

This command lists repositories within a specified GitHub organization. It retrieves the repository name, primary language, and last updated timestamp for up to 100 repositories, formatted as JSON.

```bash
gh repo list ORG --limit 100 --json name,language,updatedAt
```

--------------------------------

### Get Dependency Versions from package.json

Source: https://github.com/anivar/contributor-codebase-analyzer/blob/main/references/codebase-analysis.md

This bash script uses `cat` and `jq` to extract the entire `dependencies` object from a `package.json` file. This can be used to analyze dependency versioning, though it doesn't explicitly parse versions.

```bash
cat package.json | jq '.dependencies' 2>/dev/null
```

--------------------------------

### Shell Script for Checkpoint Management

Source: https://github.com/anivar/contributor-codebase-analyzer/blob/main/README.md

A shell script to manage the checkpointing process for the contributor analysis skill. It handles saving, resuming, checking status, and managing rate limits.

```shell
#!/bin/bash

# scripts/checkpoint.sh
# Save/resume/status/ratelimit helper for the contributor analysis skill.

# Example usage:
# ./checkpoint.sh save
# ./checkpoint.sh resume
# ./checkpoint.sh status
# ./checkpoint.sh ratelimit

case "$1" in
  save)
    echo "Saving checkpoint..."
    # Add save logic here
    ;;
  resume)
    echo "Resuming from checkpoint..."
    # Add resume logic here
    ;;
  status)
    echo "Checking status..."
    # Add status check logic here
    ;;
  ratelimit)
    echo "Checking rate limits..."
    # Add rate limit check logic here
    ;;
  *)
    echo "Usage: $0 {save|resume|status|ratelimit}"
    exit 1
    ;;
esac

exit 0

```

--------------------------------

### Identify Debt Hotspots by Module in TypeScript/TypeScriptX

Source: https://context7.com/anivar/contributor-codebase-analyzer/llms.txt

This command identifies modules with the highest concentration of technical debt markers (TODO, FIXME, HACK) in TypeScript and TypeScriptX files. It uses `grep`, `awk`, `sed`, `sort`, and `uniq` to count and rank modules based on debt markers. The output lists the top 5 modules and their respective counts.

```bash
grep -rn "TODO\|FIXME\|HACK" --include="*.ts" --include="*.tsx" | \
  awk -F: '{print $1}' | sed 's|/[^/]*$||' | sort | uniq -c | sort -rn | head -5
```

--------------------------------

### Bash: Generate IDE Context from Structure Analysis

Source: https://github.com/anivar/contributor-codebase-analyzer/blob/main/references/codebase-analysis.md

This script demonstrates how to generate IDE context files (like `.cursorrules`) by parsing a `structure.json` file. It extracts information about architecture patterns and key module paths to provide context to IDEs or other tools.

```bash
# Generate from structure analysis
echo "This is a $(cat structure.json | jq -r '.architecture_patterns | join(", ")') project."
echo "Key modules: $(cat structure.json | jq -r '.modules[].path' | head -5 | tr '\n' ', ')"
```

--------------------------------

### Detecting Hook Bypass (Git Bash)

Source: https://github.com/anivar/contributor-codebase-analyzer/blob/main/AGENTS.md

This command searches for commits authored by a specific email within a year that include 'no-verify' in their subject or body, indicating potential bypass of pre-commit hooks.

```bash
git log --author="EMAIL" --after="YEAR-01-01" --before="YEAR+1-01-01" --format="%s %b" | grep -i "no-verify"
```

--------------------------------

### Detecting Same-Day Self-Fixes (Git Bash)

Source: https://github.com/anivar/contributor-codebase-analyzer/blob/main/AGENTS.md

This command identifies commits made on the same day by the same author that include the word 'fix' or 'Fix' in their subject. It helps in assessing the frequency of immediate corrections to code.

```bash
git log --author="EMAIL" --after="YEAR-01-01" --before="YEAR+1-01-01" --format="%ad %H %s" --date=short | \
  awk '{date=$1; if(date==prev_date && ($0 ~ /fix/ || $0 ~ /Fix/)) print "SAME-DAY FIX:", $0; prev_date=date}'
```

--------------------------------

### Locate Configuration Files in Repository

Source: https://github.com/anivar/contributor-codebase-analyzer/blob/main/references/codebase-analysis.md

This bash script finds common configuration files within the first two directory levels of a repository. It searches for files matching patterns like `*.config.*`, `.eslintrc*`, `tsconfig*`, and `babel.config*`, then sorts the results.

```bash
find . -maxdepth 2 -name "*.config.*" -o -name ".eslintrc*" \
  -o -name "tsconfig*" -o -name "babel.config*" | sort
```

--------------------------------

### Analyze Languages Across GitHub Repositories

Source: https://github.com/anivar/contributor-codebase-analyzer/blob/main/AGENTS.md

Aggregates and counts programming languages used across all repositories in a GitHub organization. It fetches language statistics for each repository and sums them up. Includes validation for repository names.

```bash
for repo in $(gh repo list ORG --limit 100 --json name --jq '.[].name'); do
    [[ "$repo" =~ ^[a-zA-Z0-9._-]+$ ]] || continue
    gh api "repos/ORG/$repo/languages" 2>/dev/null | jq -r 'to_entries[] | "\(.key)\t\(.value)"'
done | awk -F'\t' '{lang[$1]+=$2} END {for(l in lang) print lang[l], l}' | sort -rn
```

--------------------------------

### List GitLab Projects (GitLab CLI)

Source: https://github.com/anivar/contributor-codebase-analyzer/blob/main/SKILL.md

This command lists projects within a specified GitLab group. It retrieves project details and outputs them in JSON format, with a configurable number of projects per page.

```bash
glab project list --group GROUP --per-page 100 -o json
```

--------------------------------

### Identifying Multi-Iteration Tickets (Git Bash)

Source: https://github.com/anivar/contributor-codebase-analyzer/blob/main/AGENTS.md

This script analyzes commit subjects to find tickets (formatted as 'TICKET-ID') that have been addressed in four or more commits. It helps identify complex issues requiring multiple iterations.

```bash
git log --author="EMAIL" --after="YEAR-01-01" --before="YEAR+1-01-01" --format="%s" | \
  grep -oP '[A-Z]+-\d+' | sort | uniq -c | sort -rn | awk '$1 >= 4'
```

--------------------------------

### List GitLab Projects

Source: https://github.com/anivar/contributor-codebase-analyzer/blob/main/references/codebase-analysis.md

This bash script uses the GitLab CLI (`glab`) to list projects within a specified group, including those in nested subgroups. It outputs the project path, language, and last activity timestamp in JSON format, then uses `jq` to format the output.

```bash
# GitLab:
glab project list --group GROUP --include-subgroups --per-page 100 -o json | \
  jq '.[] | "\(.path_with_namespace)\t\(.language)\t\(.last_activity_at)"'
```

--------------------------------

### Detecting Self-Reverts (Git Bash)

Source: https://github.com/anivar/contributor-codebase-analyzer/blob/main/AGENTS.md

This git command logs commits authored by a specific email address within a given year that contain the word 'revert' in their subject line, useful for identifying self-reverted changes.

```bash
git log --author="EMAIL" --after="YEAR-01-01" --before="YEAR+1-01-01" --grep="revert" --oneline
```

--------------------------------

### Scan GitLab Projects and Handle Rate Limits with Delays

Source: https://github.com/anivar/contributor-codebase-analyzer/blob/main/references/codebase-analysis.md

This bash script iterates through GitLab projects within a specified group, retrieves language information for each project, and prints it. It includes a small delay between API calls to comply with GitLab's per-minute rate limits, ensuring smoother execution.

```bash
for project_id in $(glab project list --group GROUP --per-page 100 -o json | jq '.[].id'); do
    glab api "projects/$project_id/languages" 2>/dev/null | \
      jq -r 'to_entries[] | "\(.key)\t\(.value)"'
    sleep 0.5
done
```

--------------------------------

### Secure Shell Command Interpolation in Bash

Source: https://github.com/anivar/contributor-codebase-analyzer/blob/main/AGENTS.md

Demonstrates the correct and incorrect methods for interpolating API output into shell commands. The secure method includes validation to prevent injection attacks, while the incorrect method is vulnerable. This is crucial for handling untrusted data from sources like GitHub API responses.

```bash
# WRONG — unsanitized API output in shell command
REPO_NAME=$(gh api repos/ORG/REPO --jq '.name')
cd "$REPO_NAME"

# RIGHT — validate before use
REPO_NAME=$(gh api repos/ORG/REPO --jq '.name')
if [[ ! "$REPO_NAME" =~ ^[a-zA-Z0-9._-]+$ ]]; then
    echo "Error: invalid repo name"
    exit 1
fi
cd "$REPO_NAME"
```

--------------------------------

### Counting Console Cleanup Commits (Git Bash)

Source: https://github.com/anivar/contributor-codebase-analyzer/blob/main/AGENTS.md

This command counts commits made by a specific author within a year that contain 'console' or 'reactotron' (case-insensitive) in their subject line, useful for tracking the removal of debug statements.

```bash
git log --author="EMAIL" --after="YEAR-01-01" --before="YEAR+1-01-01" --oneline | grep -iE "console|reactotron" | wc -l
```

--------------------------------

### Phase 2: Gather Merged PR/MR Count (GitHub CLI)

Source: https://github.com/anivar/contributor-codebase-analyzer/blob/main/AGENTS.md

Uses the GitHub CLI to search for and count the number of merged pull requests created by a specific user within a given repository and date range.

```bash
# PRs/MRs created (merged) — platform CLI
# GitHub:
gh search prs --author=USERNAME --repo=ORG/REPO --merged --merged=YEAR-01-01..YEAR-12-31 --limit=500 --json number | jq length
```