Metadata-Version: 2.4
Name: eclipse-ipa
Version: 0.2.0
Summary: Tool to perform IP Analysis of GitHub and GitLab repositories.
Project-URL: Homepage, https://projects.eclipse.org/projects/technology.dash
Project-URL: Source, https://gitlab.eclipse.org/eclipse/technology/dash/ip-analysis
Project-URL: Issues, https://gitlab.eclipse.org/eclipse/technology/dash/ip-analysis/-/issues
Project-URL: Changelog, https://gitlab.eclipse.org/eclipse/technology/dash/ip-analysis/-/blob/main/CHANGELOG.md
Author-email: André Gomes <andre.gomes@eclipse-foundation.org>
License-File: LICENSE
License-File: NOTICE.md
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Eclipse Public License 2.0 (EPL-2.0)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Requires-Dist: chardet==7.3.0
Requires-Dist: colorama==0.4.6
Requires-Dist: jinja2==3.1.6
Requires-Dist: pygithub==2.9.0
Requires-Dist: python-gitlab==8.1.0
Requires-Dist: requests==2.33.0
Description-Content-Type: text/markdown

<!--
 * Copyright (c) 2024-2026 The Eclipse Foundation
 * 
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License 2.0 which is available at
 * http://www.eclipse.org/legal/epl-2.0.
 * 
 * SPDX-FileType: DOCUMENTATION
 * SPDX-FileCopyrightText: 2024 The Eclipse Foundation
 * SPDX-License-Identifier: EPL-2.0
-->

Eclipse IP Analysis
=============
![Gitlab Pipeline Status](https://img.shields.io/gitlab/pipeline-status/eclipse%2Ftechnology%2Fdash%2Fip-analysis?gitlab_url=https%3A%2F%2Fgitlab.eclipse.org&branch=main)
![PyPI - Version](https://img.shields.io/pypi/v/eclipse-ipa)
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/eclipse-ipa)
[![REUSE status](https://api.reuse.software/badge/gitlab.eclipse.org/eclipse/technology/dash/ip-check)](https://api.reuse.software/info/gitlab.eclipse.org/eclipse/technology/dash/ip-analysis)
[![GitLab License](https://img.shields.io/gitlab/license/eclipse%2Ftechnology%2Fdash%2Fip-analysis?gitlab_url=https%3A%2F%2Fgitlab.eclipse.org&color=informational)](https://www.eclipse.org/legal/epl-2.0/)

# About

Eclipse IP Analysis (IPA) enables seamless third-party dependency analysis in GitLab and GitHub repositories and
groups/organizations using the [Eclipse Dash License Tool](https://github.com/eclipse-dash/dash-licenses).
As default output, it generates a comprehensive HTML report with the results.

_List of currently supported programming languages: Go, Java (Maven and Gradle), JavaScript (NPM and Yarn),
TypeScript (NPM and Yarn), Kotlin (Gradle), Python (PyPi and Conda)._

# Getting Started

## Base Requirements

To run the tool, you must install the base requirements described below.

- Python >=3.10: check your Python version with the command ```python3 --version```. Also, check that you
have the Python Package Manager (pip) installed. Similar to Python, you can run ```pip3 --version```. The resulting line 
should contain your version of Python at its end. If pip is not installed, official documentation can be followed 
[here](https://pip.pypa.io/en/stable/installation/).

- Java JDK 11 or above: the latest version can be safely installed. Check that Java is installed and what's the current
version by running the command ```java --version```.

- Apache Maven: the latest version can be safely installed. Check that Maven is installed and what's the current version
by running the command ```mvn --version```.

- Git CLI: the latest version can be safely installed. Check that Git is installed and what's the current version by
running the command ```git --version```.

## Install

```pip3 install eclipse-ipa```

## Build from Source (Optional)

- Clone this repository using your favorite Git software or the command line. For the command line, please execute:

```git clone https://gitlab.eclipse.org/eclipse/technology/dash/ip-analysis.git```

- Navigate to the directory of the repository that you just cloned.
- Get Hatch to build the tool (https://hatch.pypa.io/latest/install).
- Build and install the tool:

```hatch build```

```pip3 install dist/eclipse_ipa-*.whl```

([back to top](#About))

# Usage

Run the tool with the following command:

```eclipse-ipa [-h] [-ci | -e ECLIPSE_PROJECT | -gh | -gl GITLAB]```

```            [--gh-token GH_TOKEN] [--gl-token GL_TOKEN] [-v] [-b BRANCH]```

```            [-df DEPENDENCIES_FILE] [-ex EXCLUDE [EXCLUDE ...]] [-g GROUP]```

```            [-p PROJECT] [-pf PROJECTS_FILE] [-r [REVIEW]] [-c CONFIG] [-l] [-s]```

The tool does not require any of its arguments. However, a minimum set is needed to execute simple IP analysis if
a configuration file is not specified.

A summary of the arguments is given below:

```
options:
  -h, --help            show this help message and exit
  -ci, --ci-mode        Execute in CI mode (default: False)
  -e, --eclipse-project ECLIPSE_PROJECT
                        Execute for specific Eclipse Project ID (default:
                        None)
  -gh, --github         Execute for GitHub (default: False)
  -gl, --gitlab GITLAB  Execute for GitLab URL (default: gitlab.eclipse.org)
  --gh-token GH_TOKEN   GitHub token (Defaults to GITHUB_TOKEN env var)
  --gl-token GL_TOKEN   GitLab token (Defaults to GITLAB_TOKEN env var)
  -v, --version         show the version and exit

Input & Scoping:
  -b, --branch BRANCH   Branch to analyze (Defaults to default branch on each
                        repository)
  -df, --dependencies-file DEPENDENCIES_FILE
                        File with dependencies to analyze (default: None)
  -ex, --exclude EXCLUDE [EXCLUDE ...]
                        Subgroups or repositories to exclude (default: None)
  -g, --group GROUP     GitHub Organization or GitLab Group to analyze
                        (default: None)
  -p, --project PROJECT
                        Specific project/repository to analyze (default: None)
  -pf, --projects-file PROJECTS_FILE
                        File containing list of projects/repositories to analyze (default:
                        None)
  -r, --review [REVIEW]
                        Eclipse Project ID for IP review (default: None)

Configuration & Analysis:
  -c, --config CONFIG   Configuration file to use (default: config.ini)
  -l, --declared-licenses
                        Retrieve declared licenses from package repositories
                        (default: False)

Output:
  -s, --summary         Output as an Eclipse Dash summary file (default:
                        False)
```

To start using the tool, you must provide **one of the following _six_ options**:

1. An Eclipse Project ID (e.g., technology.dash). This is specified with option -e as summarized above.

2. A file with the dependencies to analyze (one per line) using the format supported by Eclipse Dash. 
The full path of this file is specified with option -df as summarized above.

3. A file with the list of GitHub/GitLab Projects to analyze. Each line should contain the GitHub/GitLab project 
complete name with namespace or URL. The full path of this file is specified with option -pf as summarized above.

Example for a GitHub line:

```kubernetes-client/python```

Example for a GitLab line:

```eclipse/technology/dash/ip-analysis```

4. A GitHub Organization, or a GitLab Group. Provide name with namespace or URL. 
This is specified with option -g as summarized above.

5. A GitHub Project, or a GitLab Project. Provide name with namespace or URL. 
This is specified with option -p as summarized above.

6. A configuration file, specified with option -c as summarized above. It allows additional customization, and a sample
is provided in the same folder as the tool with the filename *config.ini.sample*. Parameters within the config file are 
described in the comments.

_Please note that, for GitHub API public access, the API rate limits are very low. It's highly recommended to provide 
an access token in such cases._

## Usage Examples

Run for a GitHub repository:

```eclipse-ipa -gh --gh-token <GitHub Token> -p eclipse-dash/dash-licenses```

Run for a GitHub organization:

```eclipse-ipa -gh --gh-token <GitHub Token> -g eclipse-dash```

_IMPORTANT: It's highly recommended to use a GitHub token to have higher API rate limits for GitHub projects._

Run for a GitLab project:

```eclipse-ipa -gl gitlab.eclipse.org -p eclipse/technology/dash/ip-analysis```

Run for a GitLab group:

```eclipse-ipa -gl gitlab.eclipse.org -g eclipse/technology/dash```

Run for an Eclipse project (can have both GitHub and GitLab projects):

```eclipse-ipa --gh-token <GitHub Token> -e technology.dash```

_IMPORTANT: It's highly recommended to use a GitHub token to have higher API rate limits for GitHub projects._

Run for an Eclipse project and enable Automatic IP Team Review Requests:

```eclipse-ipa --gh-token <GitHub Token> --gl-token <GitLab Token> -e technology.dash -r```

_NOTE: A GitLab token is required for Automatic IP Team Review Requests (-r). For this example, the Eclipse 
Project ID will be re-used from the provided Eclipse Project (-e)._

## How the tool works

If a GitHub Organization/GitLab Group or a list of GitHub/GitLab Projects is provided, the tool fetches the programming
languages for each project and searches for dependency files for each supported programming language. Once a list of
dependency locations is found, it runs Eclipse Dash on those dependencies to analyze their IP approval status.

At the end, and by default, the tool outputs a full report in HTML. Any additional details can be found in the log file
(ip-analysis.log).

([back to top](#About))

# License

This program and the accompanying materials are made available under the terms of the Eclipse Public License 2.0, which 
is available at http://www.eclipse.org/legal/epl-2.0.

([back to top](#About))
