chore: apply lint fixes and simplify docs

Signed-off-by: Ruben Romero Montes <rromerom@redhat.com>

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: ruromero

docs/license-resolution-and-compliance.md

@@ -1,111 +1,151 @@
-# License resolution and compliance
+# License Resolution and Compliance
 
-This document describes how the client resolves the **project license** (from manifest vs repository file), how it uses the **backend licenses-by-purl endpoint** to get dependency licenses, and how **component analysis** can report when the project license is missing, inconsistent, or incompatible with dependency licenses.
+This document describes the license analysis features that help you understand your project’s license and check compatibility with your dependencies.
 
-## Goals
+## Overview
 
-1. **Resolve project license** from:
-   - The manifest (e.g. `package.json` `license`, `pom.xml` `<licenses>`) when present.
-   - A `LICENSE`, `LICENSE.md`, or `LICENSE.txt` file in the same directory as the manifest.
-2. **Report to the user** when the license declared in the manifest differs from the license text file.
-3. **Component analysis**: when the user runs component analysis (e.g. on opening a manifest), optionally check dependency licenses (via backend) and report if any are **incompatible** with the project license.
+License analysis is **enabled by default** and provides:
 
-## Resolving the project license
+1. **Project license detection** from your manifest file (e.g., `package.json`, `pom.xml`) and LICENSE files
+2. **Dependency license information** from the Trustify DA backend
+3. **Compatibility checking** to identify potential license conflicts
+4. **Mismatch detection** when your manifest and LICENSE file declare different licenses
 
-### From the manifest
+## How It Works
 
-| Ecosystem      | Manifest        | Where license is read |
-|----------------|-----------------|------------------------|
-| JavaScript     | package.json    | `license` (string) or `licenses` (array); can be SPDX id or "SEE LICENSE IN FILE" |
-| Java (Maven)   | pom.xml         | Effective POM: `<licenses><license><name>` / `<url>`; map common names to SPDX where possible |
-| Java (Gradle)  | build.gradle(*) | No standard; some projects set extra/license in properties; optional best-effort |
-| Go             | go.mod          | No standard license field |
-| Python         | requirements.txt| No license in manifest |
+### Project License Detection
 
-(*) Gradle: license is often in a separate file or NOTICE; we do not parse build logic.
+The client looks for your project’s license in two places:
 
-### From the repository (LICENSE / LICENSE.md)
+1. **Manifest file** — Reads the license field from:
+   - `package.json`: `license` field
+   - `pom.xml`: `<licenses><license><name>` element
+   - Other ecosystems: varies by ecosystem (some don’t have standard license fields)
+
+2. **LICENSE file** — Searches for `LICENSE`, `LICENSE.md`, or `LICENSE.txt` in the same directory as your manifest
 
-- Look in the **manifest directory** for `LICENSE`, `LICENSE.md`, or `LICENSE.txt`.
-- Only searches the same directory as the manifest (not parent directories or git root).
-- Read file content; try to **detect** or **normalize** to an SPDX identifier (e.g. "Apache-2.0") for comparison using local pattern matching or the backend `/licenses/identify` endpoint for more accuracy.
+The backend’s license identification API is used for accurate LICENSE file detection.
 
-### Reporting manifest vs file mismatch
+### Dependency License Information
 
-- If both manifest and file are present and indicate different licenses → set `licenseSummary.manifestVsFileMismatch: true` and include both values so the user can fix the inconsistency.
-- If only one is present, we still expose both `fromManifest` and `fromFile` so the user sees what was found.
+Dependency licenses come from the Trustify DA backend, which categorizes them as:
+- **PERMISSIVE** (MIT, Apache-2.0, BSD, etc.)
+- **WEAK_COPYLEFT** (LGPL, MPL, etc.)
+- **STRONG_COPYLEFT** (GPL, AGPL, etc.)
+- **UNKNOWN**
+
+### Compatibility Checking
+
+The client checks if dependency licenses are compatible with your project license. For example:
+- Permissive project (MIT) + permissive dependencies → ✅ Compatible
+- Permissive project (MIT) + strong copyleft dependency (GPL) → ⚠️ Potentially incompatible
 
-## Backend: License Analysis API (v5) and license data in the analysis report
+Compatibility results are included in the analysis report’s `licenseSummary`.
 
-The Trustify Dependency Analytics backend provides:
+## Configuration
 
-1. **License data in the dependency analysis report** — When using the analysis API (e.g. stack or component analysis), the JSON report includes a **`licenses`** field with license information for all dependencies. This is a **LicensesResponse**: an array of provider results, each with `status`, `summary`, and `packages` (object keyed by purl). Each package has `concluded` (with `identifiers`, `expression`, `name`, `category`) and `evidence`. Categories are: **PERMISSIVE**, **WEAK_COPYLEFT**, **STRONG_COPYLEFT**, **UNKNOWN** (see [OpenAPI v5](https://github.com/guacsec/trustify-da-api-spec/blob/main/api/v5/openapi.yaml)).
+### Disable License Checking
 
-2. **License identification endpoint** — `POST /licenses/identify` accepts a LICENSE file (binary/text) and returns the identified SPDX license. This is used to accurately identify the project's LICENSE file when more precision is needed than local pattern matching.
+License analysis runs automatically during component/stack analysis. To disable it:
 
-3. **License details endpoint** — `GET /api/v5/licenses/{spdx}` returns detailed information about a specific license by SPDX identifier, including `category`, `name`, `identifiers`, `expression`, `source`, etc. Used by the CLI `license` command to provide rich license information.
+**Environment variable:**
+```bash
+export TRUSTIFY_DA_LICENSE_CHECK=false
+```
 
-The client:
+**Programmatic option:**
+```javascript
+await componentAnalysis(‘pom.xml’, { licenseCheck: false });
+```
 
-- When running the license check **after component analysis**, it uses the `result.licenses` data from the analysis response (no extra request needed for dependency licenses).
-- For the **project LICENSE file**, it first attempts local pattern matching (fast, synchronous). During the license check (async), it can optionally call `POST /licenses/identify` for more accurate backend-based identification.
-- Normalizes the license response into a map of purl → `{ licenses: string[], category? }` and uses the backend **category** for compatibility checking (e.g. project permissive + dependency STRONG_COPYLEFT → incompatible).
+### Backend URL
 
-## Component analysis: license incompatibility report
+License analysis requires the same backend URL as dependency analysis:
+```bash
+export TRUSTIFY_DA_BACKEND_URL=https://api.trustify.dev
+```
 
-When the user runs **component analysis** (e.g. upon opening a manifest):
+## CLI Usage
 
-1. The client builds the SBOM (direct dependencies only) and sends it to the backend for the usual component analysis.
-2. By default or unless `TRUSTIFY_DA_LICENSE_CHECK=false` or an option like `licenseCheck: false` is set:
-   - **Resolve project license** from manifest (synchronous).
-   - If a LICENSE file exists, optionally call `POST /licenses/identify` to accurately identify it via the backend.
-   - Set `licenseSummary.manifestVsFileMismatch` if manifest and LICENSE file licenses differ.
-   - **Extract purls** from the SBOM that was sent (from `provided.content`).
-   - **Get dependency licenses** from the analysis result’s `licenses` array (already included in the response).
-   - For each dependency, determine if its license(s) are **compatible** with the project license, using the backend category (PERMISSIVE / WEAK_COPYLEFT / STRONG_COPYLEFT).
-   - Attach a **license summary** to the component analysis result, e.g.:
-     - `licenseSummary.projectLicenseFromManifest`
-     - `licenseSummary.projectLicenseFromFile`
-     - `licenseSummary.manifestVsFileMismatch`
-     - `licenseSummary.incompatibleDependencies`: `[{ purl, licenses, category, reason }]`
-     - `licenseSummary.dependencyLicenses`: `[{ purl, licenses, category }]`
-     - So the user can see which dependencies have licenses incompatible with the project license.
+### Get License Information
 
-The client uses the backend **category** from the analysis report’s `licenses` field, plus a small in-client compatibility matrix (e.g. permissive project + STRONG_COPYLEFT dependency → incompatible).
+```bash
+exhort license path/to/pom.xml
+```
 
-## Disabling the license check in component analysis
+**Example output:**
+```json
+{
+  "projectLicense": {
+    "fromManifest": "Apache-2.0",
+    "fromFile": "Apache-2.0",
+    "mismatch": false
+  },
+  "dependencies": {
+    "pkg:maven/com.google.guava/guava@32.1.0": {
+      "licenses": ["Apache-2.0"],
+      "category": "PERMISSIVE",
+      "compatible": true
+    },
+    "pkg:maven/org.postgresql/postgresql@42.6.0": {
+      "licenses": ["BSD-2-Clause"],
+      "category": "PERMISSIVE",
+      "compatible": true
+    }
+  }
+}
+```
 
-- **Environment variable**: `TRUSTIFY_DA_LICENSE_CHECK=false`
-- **Option**: `opts.licenseCheck = false` when calling `client.componentAnalysis(manifest, opts)`
+## Analysis Report Fields
 
-By default (unless disabled), after the component analysis response is received, the client:
-1. Resolves the project license from manifest and LICENSE file (with optional backend identification for LICENSE file)
-2. Extracts dependency licenses from `result.licenses` in the analysis response
-3. Computes compatibility and attaches a `licenseSummary` to the report
+When license checking is enabled, the analysis report includes:
 
-## API surface (client)
-
-- **Project license resolution** (local, synchronous):
-  - `getProjectLicense(manifestPath, opts)` → `{ fromManifest, fromFile, mismatch }`
-  - `getProjectLicenseFromManifestOnly(manifestPath, opts)` → `{ fromManifest, fromFile: null, mismatch: false }`
-  - `findLicenseFilePath(manifestPath)` → `string|null` (path to LICENSE file)
-
-- **Backend license identification and details**:
-  - `identifyLicenseViaBackend(licenseFilePath, backendUrl, opts)` → `Promise<string|null>` (SPDX id from `POST /licenses/identify`)
-  - `getLicenseDetails(spdxId, backendUrl, opts)` → `Promise<Object|null>` (detailed license info from `GET /api/v5/licenses/{spdx}`, includes category, name, identifiers, etc.)
-
-- **Dependency licenses from analysis report**:
-  - `licenseMapFromAnalysisReport(analysisReport, purls?)` → `Map<purl, { licenses, category? }>`
-  - Extracts license data from the analysis response's `licenses` field (no extra request)
-
-- **Full license check** (for component analysis):
-  - `runLicenseCheck(sbomContent, manifestPath, backendUrl, opts, analysisResult)` → `Promise<LicenseSummary>`
-  - Uses `analysisResult.licenses` for dependency licenses. Optionally calls `POST /licenses/identify` for accurate project LICENSE file identification. Used inside `componentAnalysis()` when license check is enabled; result is attached as `report.licenseSummary`.
-
-- **Compatibility checking**:
-  - `getCompatibility(projectLicense, dependencyLicenses[], dependencyCategory?)` → `'compatible' | 'incompatible' | 'unknown'`
-
-- **Utility** (typically not needed):
-  - `getLicensesByPurl(purls, backendUrl, opts)` → `Promise<Map<purl, { licenses, category? }>>` (standalone call to `POST /api/v5/licenses`)
-
-Options (e.g. proxy, token) are passed through to the backend fetch in the same way as for analysis requests.
+```javascript
+{
+  // ... standard analysis fields ...
+  "licenseSummary": {
+    "projectLicenseFromManifest": "Apache-2.0",
+    "projectLicenseFromFile": "Apache-2.0",
+    "manifestVsFileMismatch": false,
+    "incompatibleDependencies": [
+      {
+        "purl": "pkg:maven/org.example/gpl-lib@1.0.0",
+        "licenses": ["GPL-3.0"],
+        "category": "STRONG_COPYLEFT",
+        "reason": "Dependency license(s) are incompatible with the project license."
+      }
+    ],
+    "dependencyLicenses": [
+      { "purl": "...", "licenses": [...], "category": "..." }
+    ]
+  }
+}
+```
+
+## Common Scenarios
+
+### Mismatch Between Manifest and LICENSE File
+
+If your `package.json` says `"license": "MIT"` but your LICENSE file contains Apache-2.0 text:
+```json
+{
+  "projectLicenseFromManifest": "MIT",
+  "projectLicenseFromFile": "Apache-2.0",
+  "manifestVsFileMismatch": true
+}
+```
+
+**Action:** Update your manifest or LICENSE file to match.
+
+### Incompatible Dependencies
+
+If you have a permissive-licensed project (MIT, Apache) but depend on GPL-licensed libraries, they’ll appear in `incompatibleDependencies`.
+
+**Action:** Review the flagged dependencies and consider:
+- Finding alternative libraries with compatible licenses
+- Consulting legal counsel if the dependency is necessary
+- Understanding how you’re using the dependency (linking, distribution, etc.)
+
+## SBOM Integration
+
+Project license information is automatically included in generated SBOMs (CycloneDX format) in the root component’s `licenses` field.

src/analysis.js

@@ -4,10 +4,9 @@ import { EOL } from "os";
 
 import { HttpsProxyAgent } from "https-proxy-agent";
 
-import { generateImageSBOM, parseImageRef } from "./oci_image/utils.js";
 import { runLicenseCheck } from "./license/index.js";
-import { getCustom, getTokenHeaders } from "./tools.js";
-import { TRUSTIFY_DA_OPERATION_TYPE_HEADER, TRUSTIFY_DA_PACKAGE_MANAGER_HEADER } from "./tools.js";
+import { generateImageSBOM, parseImageRef } from "./oci_image/utils.js";
+import { getCustom, getTokenHeaders , TRUSTIFY_DA_OPERATION_TYPE_HEADER, TRUSTIFY_DA_PACKAGE_MANAGER_HEADER } from "./tools.js";
 
 export default { requestComponent, requestStack, requestImages, validateToken }
 

src/cli.js

@@ -5,9 +5,10 @@ import * as path from "path";
 import yargs from 'yargs'
 import { hideBin } from 'yargs/helpers'
 
-import client from './index.js'
 import { getProjectLicense, getLicenseDetails } from './license/index.js'
 
+import client from './index.js'
+
 
 // command for component analysis take manifest type and content
 const component = {
@@ -203,7 +204,7 @@ const license = {
 
 		// Build LicenseInfo objects
 		const buildLicenseInfo = async (spdxId) => {
-			if (!spdxId) return null
+			if (!spdxId) {return null}
 
 			const licenseInfo = { spdxId }
 

src/cyclone_dx_sbom.js

@@ -43,12 +43,11 @@ function getComponent(component, type, scope, licenses) {
 		componentObject = component
 	}
 
-	// Add licenses if provided (CycloneDX format)
+	// Add licenses if provided (CycloneDX format). Callers must provide valid SPDX identifiers.
 	if (licenses) {
 		const licenseArray = Array.isArray(licenses) ? licenses : [licenses];
 		componentObject.licenses = licenseArray.map(lic => {
 			if (typeof lic === 'string') {
-				// If it's a string, treat it as an SPDX id or name
 				return { license: { id: lic } };
 			}
 			return lic;

src/license/compatibility.js

@@ -13,37 +13,38 @@
  * @returns {'compatible'|'incompatible'|'unknown'}
  */
 export function getCompatibility(projectLicense, dependencyLicenses, dependencyCategory) {
-	if (!projectLicense && !dependencyLicenses?.length) return 'unknown';
+	if (!projectLicense) {return 'unknown';}
+	if (!dependencyLicenses?.length) {return 'unknown';}
 
 	// Use backend category when available (from API v5 licenses / analysis report)
 	const cat = String(dependencyCategory || '').toUpperCase();
 	if (cat === 'STRONG_COPYLEFT') {
 		const proj = projectLicense ? normalize(projectLicense) : '';
-		if (isPermissive(proj)) return 'incompatible';
-		if (isCopyleft(proj)) return 'unknown';
+		if (isPermissive(proj)) {return 'incompatible';}
+		if (isCopyleft(proj)) {return 'unknown';}
 		return 'incompatible';
 	}
 	if (cat === 'WEAK_COPYLEFT') {
 		const proj = projectLicense ? normalize(projectLicense) : '';
-		if (isPermissive(proj)) return 'unknown'; // weak copyleft often acceptable when used as library
+		if (isPermissive(proj)) {return 'unknown';} // weak copyleft often acceptable when used as library
 		return 'unknown';
 	}
-	if (cat === 'PERMISSIVE' && (!projectLicense || isPermissive(normalize(projectLicense)))) return 'compatible';
+	if (cat === 'PERMISSIVE' && (!projectLicense || isPermissive(normalize(projectLicense)))) {return 'compatible';}
 
-	if (!projectLicense || !dependencyLicenses?.length) return 'unknown';
+	if (!projectLicense || !dependencyLicenses?.length) {return 'unknown';}
 
 	const proj = normalize(projectLicense);
 	const depSet = new Set(dependencyLicenses.map(normalize).filter(Boolean));
 
 	// Same license or both permissive -> compatible
-	if (depSet.has(proj)) return 'compatible';
-	if (isPermissive(proj) && [...depSet].every(isPermissive)) return 'compatible';
+	if (depSet.has(proj)) {return 'compatible';}
+	if (isPermissive(proj) && [...depSet].every(isPermissive)) {return 'compatible';}
 
 	// Project is permissive; dependency is copyleft -> flag for user awareness
-	if (isPermissive(proj) && [...depSet].some(isCopyleft)) return 'incompatible';
+	if (isPermissive(proj) && [...depSet].some(isCopyleft)) {return 'incompatible';}
 
 	// Project is copyleft; dependency is different copyleft or proprietary -> unknown / depends on linking
-	if (isCopyleft(proj)) return 'unknown';
+	if (isCopyleft(proj)) {return 'unknown';}
 
 	return 'unknown';
 }

src/license/index.js

@@ -2,11 +2,11 @@
  * License resolution and dependency license compatibility for component analysis.
  */
 
-import { getProjectLicense, findLicenseFilePath, identifyLicenseViaBackend } from './project_license.js';
+import { getProjectLicense, findLicenseFilePath, identifyLicense } from './project_license.js';
 import { licenseMapFromAnalysisReport } from './licenses_api.js';
 import { getCompatibility } from './compatibility.js';
 
-export { getProjectLicense, getProjectLicenseFromManifest, findLicenseFilePath, identifyLicenseViaBackend } from './project_license.js';
+export { getProjectLicense, getProjectLicenseFromManifest, findLicenseFilePath, identifyLicense as identifyLicenseViaBackend } from './project_license.js';
 export { licenseMapFromAnalysisReport, normalizeLicensesResponse, getLicensesByPurl, getLicenseDetails } from './licenses_api.js';
 export { getCompatibility } from './compatibility.js';
 
@@ -58,7 +58,7 @@ export async function runLicenseCheck(sbomContent, manifestPath, backendUrl, opt
 	const licenseFilePath = findLicenseFilePath(manifestPath);
 	if (licenseFilePath && backendUrl) {
 		try {
-			projectLicenseFromFileBackend = await identifyLicenseViaBackend(licenseFilePath, backendUrl, opts);
+			projectLicenseFromFileBackend = await identifyLicense(licenseFilePath, backendUrl, opts);
 		} catch {
 			// Fall back to local detection (already in projectLicense.fromFile)
 		}