Merge pull request #81 from scanoss/feature/mdaloia/update-docs

Add scanoss settings schema docs

.gitignore

@@ -27,5 +27,5 @@ docs/build
 .devcontainer/devcontainer.json
 !.devcontainer/*.example.json
 
-
 !tests/data/*.json
+!docs/source/_static/*.json

docs/source/_static/scanoss-settings-schema.json

@@ -0,0 +1,132 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema",
+  "title": "Scanoss Settings",
+  "type": "object",
+  "properties": {
+    "self": {
+      "type": "object",
+      "description": "Description of the project under analysis",
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Name of the project"
+        },
+        "license": {
+          "type": "string",
+          "description": "License of the project"
+        },
+        "description": {
+          "type": "string",
+          "description": "Description of the project"
+        }
+      }
+    },
+    "bom": {
+      "type": "object",
+      "description": "BOM Rules: Set of rules that will be used to modify the BOM before and after the scan is completed",
+      "properties": {
+        "include": {
+          "type": "array",
+          "description": "Set of rules to be added as context when scanning. This list will be sent as payload to the API.",
+          "items": {
+            "type": "object",
+            "properties": {
+              "path": {
+                "type": "string",
+                "description": "File path",
+                "examples": ["/path/to/file", "/path/to/another/file"],
+                "items": {
+                  "type": "string"
+                },
+                "uniqueItems": true
+              },
+              "purl": {
+                "type": "string",
+                "description": "Package URL to be used to match the component",
+                "examples": [
+                  "pkg:npm/vue@2.6.12",
+                  "pkg:golang/github.com/golang/go@1.17.3"
+                ]
+              },
+              "comment": {
+                "type": "string",
+                "description": "Additional notes or comments"
+              }
+            },
+            "uniqueItems": true,
+            "required": ["purl"]
+          }
+        },
+        "remove": {
+          "type": "array",
+          "description": "Set of rules that will remove files from the results file after the scan is completed.",
+          "items": {
+            "type": "object",
+            "properties": {
+              "path": {
+                "type": "string",
+                "description": "File path",
+                "examples": ["/path/to/file", "/path/to/another/file"]
+              },
+              "purl": {
+                "type": "string",
+                "description": "Package URL",
+                "examples": [
+                  "pkg:npm/vue@2.6.12",
+                  "pkg:golang/github.com/golang/go@1.17.3"
+                ]
+              },
+              "comment": {
+                "type": "string",
+                "description": "Additional notes or comments"
+              }
+            },
+            "uniqueItems": true,
+            "required": ["purl"]
+          }
+        },
+        "replace": {
+          "type": "array",
+          "description": "Set of rules that will replace components with the specified one after the scan is completed.",
+          "items": {
+            "type": "object",
+            "properties": {
+              "path": {
+                "type": "string",
+                "description": "File path",
+                "examples": ["/path/to/file", "/path/to/another/file"]
+              },
+              "purl": {
+                "type": "string",
+                "description": "Package URL to replace",
+                "examples": [
+                  "pkg:npm/vue@2.6.12",
+                  "pkg:golang/github.com/golang/go@1.17.3"
+                ]
+              },
+              "comment": {
+                "type": "string",
+                "description": "Additional notes or comments"
+              },
+              "license": {
+                "type": "string",
+                "description": "License of the component. Should be a valid SPDX license expression",
+                "examples": ["MIT", "Apache-2.0"]
+              },
+              "replace_with": {
+                "type": "string",
+                "description": "Package URL to replace with",
+                "examples": [
+                  "pkg:npm/vue@2.6.12",
+                  "pkg:golang/github.com/golang/go@1.17.3"
+                ]
+              }
+            },
+            "uniqueItems": true,
+            "required": ["purl", "replace_with"]
+          }
+        }
+      }
+    }
+  }
+}

docs/source/conf.py

@@ -6,23 +6,23 @@
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-project = 'Documentation for scanoss-py'
-copyright = '2024, Scan Open Source Solutions SL'
-author = 'Scan Open Source Solutions SL'
+
+project = "Documentation for scanoss-py"
+copyright = "2024, Scan Open Source Solutions SL"
+author = "Scan Open Source Solutions SL"
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 extensions = []
 
-templates_path = ['_templates']
+templates_path = ["_templates"]
 exclude_patterns = []
 
 
-
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = 'furo'
-html_logo = 'scanosslogo.png'
-html_static_path = ['_static']
+html_theme = "furo"
+html_logo = "scanosslogo.png"
+html_static_path = ["_static"]

docs/source/index.rst

@@ -46,6 +46,8 @@ To enable dependency scanning, an extra tool is required: scancode-toolkit.
 To install it run: ``pip3 install -r requirements-scancode.txt``
 
 
+.. include:: scanoss_settings_schema.rst
+
 
 Commands and arguments
 ======================

docs/source/scanoss_settings_schema.rst

@@ -0,0 +1,175 @@
+Settings File
+======================
+
+SCANOSS provides a settings file to customize the scanning process. The settings file is a JSON file that contains project information and BOM (Bill of Materials) rules. It allows you to include, remove, or replace components in the BOM before and after scanning.
+
+The schema is available to download :download:`here </_static/scanoss-settings-schema.json>`
+
+Schema Overview
+---------------
+
+The settings file consists of two main sections:
+
+Project Information
+-------------------
+
+The ``self`` section contains basic information about your project:
+
+.. code-block:: json
+
+    {
+        "self": {
+            "name": "my-project",
+            "license": "MIT",
+            "description": "Project description"
+        }
+    }
+
+BOM Rules
+---------
+
+The ``bom`` section defines rules for modifying the BOM before and after scanning. It contains three main operations:
+
+1. Include Rules
+~~~~~~~~~~~~~~~~
+
+Rules for adding context when scanning. These rules will be sent to the SCANOSS API meaning they have more chance of being considered part of the resulting scan. 
+
+.. code-block:: json
+
+    {
+        "bom": {
+            "include": [
+                {
+                    "path": "/path/to/file",
+                    "purl": "pkg:npm/vue@2.6.12",
+                    "comment": "Optional comment"
+                }
+            ]
+        }
+    }
+
+2. Remove Rules
+~~~~~~~~~~~~~~~
+
+Rules for removing files from results after scanning. These rules will be applied to the results file after scanning. The post processing happens on the client side.
+
+.. code-block:: json
+
+    {
+        "bom": {
+            "remove": [
+                {
+                    "path": "/path/to/file",
+                    "purl": "pkg:npm/vue@2.6.12",
+                    "comment": "Optional comment"
+                }
+            ]
+        }
+    }
+
+3. Replace Rules
+~~~~~~~~~~~~~~~~
+
+Rules for replacing components after scanning. These rules will be applied to the results file after scanning. The post processing happens on the client side.
+
+.. code-block:: json
+
+    {
+        "bom": {
+            "replace": [
+                {
+                    "path": "/path/to/file",
+                    "purl": "pkg:npm/vue@2.6.12",
+                    "replace_with": "pkg:npm/vue@2.6.14",
+                    "license": "MIT",
+                    "comment": "Optional comment"
+                }
+            ]
+        }
+    }
+
+Important Notes
+---------------
+
+Matching Rules
+~~~~~~~~~~~~~~
+
+1. **Full Match**: Requires both PATH and PURL to match. It means the rule will be applied ONLY to the specific file with the matching PURL and PATH.
+2. **Partial Match**: Matches based on either:
+   - File path only (PURL is optional). It means the rule will be applied to all files with the matching path.
+   - PURL only (PATH is optional). It means the rule will be applied to all files with the matching PURL.
+
+File Paths
+~~~~~~~~~~
+
+- All paths should be specified relative to the scanned directory
+- Use forward slashes (``/``) as path separators
+
+Given the following example directory structure:
+
+.. code-block:: text
+
+    project/
+    ├── src/
+    │   └── component.js
+    └── lib/
+        └── utils.py
+
+- If the scanned directory is ``/project/src``, then:
+    - ``component.js`` is a valid path
+    - ``lib/utils.py`` is an invalid path and will not match any files
+- If the scanned directory is ``/project``, then:
+    - ``src/component.js`` is a valid path
+    - ``lib/utils.py`` is a valid path
+
+Package URLs (PURLs)
+~~~~~~~~~~~~~~~~~~~~
+
+PURLs must follow the Package URL specification:
+
+- Format: ``pkg:<type>/<namespace>/<name>@<version>``
+- Examples:
+  - ``pkg:npm/vue@2.6.12``
+  - ``pkg:golang/github.com/golang/go@1.17.3``
+- Must be valid and include all required components
+- Version is strongly recommended but optional
+
+Example Configuration
+---------------------
+
+Here's a complete example showing all sections:
+
+.. code-block:: json
+
+    {
+        "self": {
+            "name": "example-project",
+            "license": "Apache-2.0",
+            "description": "Example project configuration"
+        },
+        "bom": {
+            "include": [
+                {
+                    "path": "src/lib/component.js",
+                    "purl": "pkg:npm/lodash@4.17.21",
+                    "comment": "Include lodash dependency"
+                }
+            ],
+            "remove": [
+                {
+                    "purl": "pkg:npm/deprecated-pkg@1.0.0",
+                    "comment": "Remove deprecated package"
+                }
+            ],
+            "replace": [
+                {
+                    "path": "src/utils/helper.js",
+                    "purl": "pkg:npm/old-lib@1.0.0",
+                    "replace_with": "pkg:npm/new-lib@2.0.0",
+                    "license": "MIT",
+                    "comment": "Upgrade to newer version"
+                }
+            ]
+        }
+    }