Remote Repository Analysis

Remote Repository Analysis

Arxo can analyze remote Git repositories directly without requiring a local clone, making it easy to audit open-source projects, evaluate dependencies, or analyze repositories in CI/CD without manual checkout.

Why Analyze Remotely?

Use Cases:

• Dependency audits - Check architecture quality before adding dependencies
• Open-source evaluation - Assess project health before adoption
• Competitive analysis - Study architectural patterns in similar projects
• Security reviews - Quick architecture assessment without local setup
• CI/CD - Analyze repositories as part of automated workflows
• Multi-repo analysis - Batch analysis across multiple repositories

Benefits:

• No local clone required
• Automatic cleanup after analysis
• Works with private repositories (via credentials)
• Analyze specific branches, tags, or commits
• Built-in caching for repeated analysis

---

Basic Usage

Analyze a Public Repository

arxo analyze --repo https://github.com/user/project

This will:

1. Clone the repository to a temporary directory
2. Run analysis using default configuration
3. Display results
4. Clean up temporary files

Analyze a Specific Branch

arxo analyze \
  --repo https://github.com/user/project \
  --ref develop

Analyze a Specific Tag

arxo analyze \
  --repo https://github.com/user/project \
  --ref v2.0.0

Analyze a Specific Commit

arxo analyze \
  --repo https://github.com/user/project \
  --ref abc1234

---

Advanced Options

With Custom Configuration

arxo analyze \
  --repo https://github.com/user/project \
  --config .arxo.yaml \
  --preset ci

Note: The config file must exist in the remote repository.

With Output Format

arxo analyze \
  --repo https://github.com/user/project \
  --format json \
  --output report.json

Bypass Cache

Force a fresh clone:

arxo analyze \
  --repo https://github.com/user/project \
  --no-cache

Quiet Mode

Suppress progress output:

arxo analyze \
  --repo https://github.com/user/project \
  --quiet

---

Private Repositories

HTTPS with Credentials

Use Git credential helpers for private repos:

# GitHub Personal Access Token
git config --global credential.helper store
echo "https://USERNAME:TOKEN@github.com" >> ~/.git-credentials

arxo analyze --repo https://github.com/private-org/project

SSH Authentication

Use SSH URLs with configured keys:

# Ensure SSH key is added to ssh-agent
ssh-add ~/.ssh/id_rsa

arxo analyze --repo git@github.com:private-org/project.git

Environment Variables

# GitHub
GH_TOKEN=ghp_xxx arxo analyze --repo https://github.com/private-org/project

# GitLab
GITLAB_TOKEN=glpat-xxx arxo analyze --repo https://gitlab.com/private-org/project

---

Caching Behavior

Arxo caches remote repository clones to speed up repeated analysis.

Cache Location

~/.cache/arxo/repos/

# View cache path
arxo cache path

Cache Management

# List cached repositories
arxo cache list

# Clear all cached repos
arxo cache clear

# Analyze with fresh clone (bypass cache)
arxo analyze --repo https://github.com/user/project --no-cache

Cache Key

Repositories are cached by:

• Repository URL
• Git ref (branch/tag/commit)

Different refs of the same repo are cached separately.

---

Batch Analysis

Analyze multiple repositories in a script:

#!/bin/bash

REPOS=(
  "https://github.com/facebook/react"
  "https://github.com/vuejs/vue"
  "https://github.com/angular/angular"
)

for repo in "${REPOS[@]}"; do
  echo "Analyzing: $repo"

  arxo analyze \
    --repo "$repo" \
    --preset quick \
    --format json \
    --output "$(basename $repo).json"
done

---

CI/CD Integration

GitHub Actions

Analyze external repositories as part of your workflow:

name: Dependency Analysis

on:
  schedule:
    - cron: '0 0 * * 0'  # Weekly

jobs:
  analyze-deps:
    runs-on: ubuntu-latest

    steps:
      - name: Install Arxo
        run: |
          curl -sL "https://github.com/arxohq/arxo/releases/latest/download/arxo-linux-x86_64.tar.gz" | tar xz
          chmod +x arxo && sudo mv arxo /usr/local/bin/

      - name: Analyze Dependencies
        run: |
          # Analyze a key dependency
          arxo analyze \
            --repo https://github.com/axios/axios \
            --ref main \
            --preset security \
            --format json \
            --output axios-report.json

      - name: Check Results
        run: |
          # Fail if security issues found
          if jq -e '.violations | length > 0' axios-report.json; then
            echo "Security issues detected!"
            exit 1
          fi

      - name: Upload Report
        uses: actions/upload-artifact@v3
        with:
          name: dependency-reports
          path: "*.json"

GitLab CI

analyze_dependencies:
  stage: test
  image: ubuntu:22.04

  before_script:
    - apt-get update && apt-get install -y curl
    - curl -sL "https://github.com/arxohq/arxo/releases/latest/download/arxo-linux-x86_64.tar.gz" | tar xz
    - chmod +x arxo && mv arxo /usr/local/bin/

  script:
    - |
      arxo analyze \
        --repo https://github.com/lodash/lodash \
        --preset security \
        --format json \
        --output lodash-report.json

  artifacts:
    paths:
      - lodash-report.json
    reports:
      junit: lodash-report.xml

---

Comparison Workflow

Compare your project against reference architectures:

#!/bin/bash

# Analyze your project
arxo analyze --preset coupling --output my-project.json

# Analyze reference project
arxo analyze \
  --repo https://github.com/reference/project \
  --preset coupling \
  --output reference.json

# Compare metrics
jq -s '
  {
    my_coupling: .[0].results[] | select(.id=="pc") | .values.system,
    ref_coupling: .[1].results[] | select(.id=="pc") | .values.system
  }
' my-project.json reference.json

---

Use Cases

1. Dependency Evaluation

Before adding a new dependency:

arxo analyze \
  --repo https://github.com/axios/axios \
  --preset risk \
  --format html \
  --output axios-audit.html

open axios-audit.html

Check for:

• Circular dependencies (scc.max_cycle_size)
• Coupling level (propagation_cost.system.ratio)
• Code smells (smells.*)
• Maintenance burden (msr.*)

2. Open Source Project Assessment

Evaluate project health before contributing:

arxo analyze \
  --repo https://github.com/open-source/project \
  --ref main \
  --preset full \
  --format json \
  --output assessment.json

# Extract key metrics
jq '.results[] | {
  id: .id,
  status: .status,
  key_values: .values
}' assessment.json

3. Competitor Analysis

Study architectural patterns (public repositories only):

#!/bin/bash

COMPETITORS=(
  "https://github.com/competitor1/product"
  "https://github.com/competitor2/product"
  "https://github.com/competitor3/product"
)

for repo in "${COMPETITORS[@]}"; do
  name=$(basename $repo)

  arxo analyze \
    --repo "$repo" \
    --preset coupling \
    --format json \
    --output "$name-analysis.json"
done

# Compare coupling across competitors
jq -s 'map({
  name: input_filename,
  coupling: .results[] | select(.id=="pc") | .values.system
})' *-analysis.json

4. Security Audit

Audit dependencies for security patterns:

arxo analyze \
  --repo https://github.com/vendor/library \
  --preset security \
  --format json \
  --output security-audit.json

# Check for sensitive data flow issues
jq '.results[] | select(.id=="sensitive_data_flow")' security-audit.json

5. Historical Analysis

Analyze different points in history:

#!/bin/bash

REPO="https://github.com/user/project"
TAGS=("v1.0.0" "v2.0.0" "v3.0.0")

for tag in "${TAGS[@]}"; do
  arxo analyze \
    --repo "$REPO" \
    --ref "$tag" \
    --preset quick \
    --format json \
    --output "analysis-$tag.json"
done

# Track metric evolution
jq -s 'map({
  version: input_filename | match("v[0-9.]+") | .string,
  cycles: (.results[] | select(.id=="scc") | .data[] | select(.key=="scc.max_cycle_size") | .value.v),
  coupling: (.results[] | select(.id=="propagation_cost") | .data[] | select(.key=="propagation_cost.system.ratio") | .value.v)
})' analysis-*.json

---

Troubleshooting

Clone Timeout

Error: “Failed to clone repository: timeout”

Solutions:

1. Check network connectivity:

   git clone https://github.com/user/project test-clone
   rm -rf test-clone

2. Use SSH instead of HTTPS:

   arxo analyze --repo git@github.com:user/project.git

3. Increase timeout (not configurable yet - contact support)

---

Authentication Failed

Error: “Authentication failed”

Solutions:

1. Check credentials:

   # Test Git access
   git ls-remote https://github.com/private-org/project

2. Use personal access token:

   git config --global credential.helper store
   echo "https://USERNAME:TOKEN@github.com" >> ~/.git-credentials

3. Use SSH:

   ssh -T git@github.com  # Test SSH access
   arxo analyze --repo git@github.com:private-org/project.git

---

Repository Not Found

Error: “Repository not found”

Causes:

• Incorrect URL
• Private repository without credentials
• Repository deleted or renamed

Solution:

# Verify URL
git ls-remote <URL>

# Check repository exists
curl -I https://github.com/user/project

---

Cache Issues

Issue: Analysis shows stale results

Solution:

# Clear cache and re-analyze
arxo cache clear
arxo analyze --repo https://github.com/user/project --no-cache

---

Large Repository

Issue: Clone takes too long or fails

Solutions:

1. Use shallow clone (not configurable yet)

2. Analyze specific subdirectory:

   # Clone manually with depth=1
   git clone --depth=1 https://github.com/user/large-project
   cd large-project
   arxo analyze --path ./subdirectory

3. Exclude unnecessary files: Add .arxo.yaml to repository:

   data:
     import_graph:
       exclude:
         - "**/test/**"
         - "**/docs/**"
         - "**/examples/**"

---

Security Considerations

1. Credential Safety

Do NOT hardcode credentials:

# ❌ Bad
arxo analyze --repo https://user:password@github.com/project

# ✅ Good
git config --global credential.helper store
arxo analyze --repo https://github.com/project

2. Untrusted Repositories

Be cautious when analyzing untrusted repositories:

# Analyze in isolated environment
docker run --rm -v /tmp/reports:/reports ubuntu:22.04 sh -c "
  apt-get update && apt-get install -y curl &&
  curl -sL https://github.com/arxohq/arxo/releases/latest/download/arxo-linux-x86_64.tar.gz | tar xz &&
  chmod +x arxo && ./arxo analyze --repo https://untrusted.com/repo --output /reports/report.json
"

3. Private Repository Access

Limit token permissions:

GitHub: Use fine-grained tokens with read-only repository access

GitLab: Use project access tokens with read_repository scope

4. Cleanup

Remote analysis cleans up automatically, but verify:

# Check for leftover clones
ls ~/.cache/arxo/repos/

# Manual cleanup if needed
arxo cache clear

---

Performance Tips

1. Use Caching

Don’t bypass cache unless necessary:

# ✅ Good (uses cache)
arxo analyze --repo https://github.com/user/project

# ❌ Slower (always clones fresh)
arxo analyze --repo https://github.com/user/project --no-cache

2. Use Quick Preset for Exploratory Analysis

# Fast initial assessment
arxo analyze --repo https://github.com/user/project --quick

# Deep dive only if needed
arxo analyze --repo https://github.com/user/project --preset full

3. Parallel Analysis

Analyze multiple repos in parallel:

#!/bin/bash

REPOS=(
  "https://github.com/user/project1"
  "https://github.com/user/project2"
  "https://github.com/user/project3"
)

# Run in parallel
for repo in "${REPOS[@]}"; do
  (
    name=$(basename $repo)
    arxo analyze --repo "$repo" --output "$name.json"
  ) &
done

wait

---

Comparison with Local Analysis

Feature	Local Analysis	Remote Analysis
Setup	Manual clone required	Automatic
Disk space	Repository stays on disk	Auto cleanup
Speed	Faster (no clone)	Slower (clone time)
Caching	Analysis cache only	Clone + analysis cache
Git history	Full history available	Full history available
Credentials	Use git config	Use git config
CI/CD	Requires checkout step	All-in-one

---

AI-Assisted Remote Analysis

Use the MCP server with your AI assistant to analyze remote repositories conversationally:

You: "Analyze the architecture of https://github.com/axios/axios"
AI: [Runs analyze_architecture with repo URL]
    "Found 247 files, no circular dependencies, coupling: 0.12..."

You: "How does that compare to our project?"
AI: [Compares metrics] "Your coupling is higher at 0.18..."

See MCP Workflows for AI-driven analysis patterns.

---

Next Steps

• CI Integration - Integrate remote analysis in pipelines
• Baseline Comparison - Compare across refs
• MCP Workflows - AI-assisted architecture analysis
• Policy Examples - Enforce quality gates
• Output Formats - Export results
• Troubleshooting - Common issues