feat(settings):SP-384 Implement scan configuration parameters

Author: Gepeto Escalante

CHANGELOG.md

@@ -7,9 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.13.0] - 2026-02-03
 ### Added
+- Added `file_snippet` scan configuration support in `scanoss.json` for engine tuning parameters (`min_snippet_hits`, `min_snippet_lines`, `honour_file_exts`, `ranking_enabled`, `ranking_threshold`, `skip_headers`, `skip_headers_limit`)
+- Added CLI scan configuration options with resolution priority (file_snippet > CLI)
+- Added `FileSnippet` class for scan configuration management and resolution
 
-- Upcoming changes...
 ## [0.12.1] - 2026-01-08
 ### Changed
 - Updated slf4j from 2.0.16 to 2.0.17
@@ -141,4 +144,5 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [0.10.1]: https://github.com/scanoss/scanoss.java/compare/v0.10.0...v0.10.1
 [0.11.0]: https://github.com/scanoss/scanoss.java/compare/v0.10.1...v0.11.0
 [0.12.0]: https://github.com/scanoss/scanoss.java/compare/v0.11.0...v0.12.0
-[0.12.1]: https://github.com/scanoss/scanoss.java/compare/v0.12.0...v0.12.1
+[0.12.1]: https://github.com/scanoss/scanoss.java/compare/v0.12.0...v0.12.1
+[0.13.0]: https://github.com/scanoss/scanoss.java/compare/v0.12.1...v0.13.0

pom.xml

@@ -6,7 +6,7 @@
 
     <groupId>com.scanoss</groupId>
     <artifactId>scanoss</artifactId>
-    <version>0.12.1</version>
+    <version>0.13.0</version>
     <packaging>jar</packaging>
     <name>scanoss.java</name>
     <url>https://github.com/scanoss/scanoss.java</url>

src/main/java/com/scanoss/Scanner.java

@@ -31,6 +31,7 @@
 import com.scanoss.processor.*;
 import com.scanoss.rest.ScanApi;
 import com.scanoss.settings.Bom;
+import com.scanoss.settings.FileSnippet;
 import com.scanoss.settings.ScanossSettings;
 import com.scanoss.utils.JsonUtils;
 import lombok.*;
@@ -116,7 +117,8 @@ private Scanner(Boolean skipSnippets, Boolean allExtensions, Boolean obfuscate,
                     Integer snippetLimit, String customCert, Proxy proxy,
                     Winnowing winnowing, ScanApi scanApi,
                     ScanFileProcessor scanFileProcessor, WfpFileProcessor wfpFileProcessor,
-                    ScanossSettings settings, ScannerPostProcessor postProcessor, FilterConfig filterConfig,
+                    ScanossSettings settings,
+                    ScannerPostProcessor postProcessor, FilterConfig filterConfig,
                     Predicate<Path> fileFilter,
                     Predicate<Path> folderFilter
     ) {
@@ -137,20 +139,24 @@ private Scanner(Boolean skipSnippets, Boolean allExtensions, Boolean obfuscate,
         this.snippetLimit = snippetLimit;
         this.customCert = customCert;
         this.proxy = proxy;
+        this.settings = Objects.requireNonNullElseGet(settings, () -> ScanossSettings.builder().build());
+
+        FileSnippet resolvedSnippet = this.settings.getSettings().getFileSnippet();
         this.winnowing = Objects.requireNonNullElseGet(winnowing, () ->
                 Winnowing.builder().skipSnippets(skipSnippets).allExtensions(allExtensions).obfuscate(obfuscate)
                         .hpsm(hpsm).snippetLimit(snippetLimit)
+                        .skipHeaders(resolvedSnippet != null && Boolean.TRUE.equals(resolvedSnippet.getSkipHeaders()))
+                        .skipHeadersLimit(resolvedSnippet != null && resolvedSnippet.getSkipHeadersLimit() != null ? resolvedSnippet.getSkipHeadersLimit() : 0)
                         .build());
         this.scanApi = Objects.requireNonNullElseGet(scanApi, () ->
                 ScanApi.builder().url(url).apiKey(apiKey).timeout(timeout).retryLimit(retryLimit).flags(scanFlags)
-                        .sbomType(sbomType).sbom(sbom).customCert(customCert).proxy(proxy).settings(settings)
+                        .sbomType(sbomType).sbom(sbom).customCert(customCert).proxy(proxy).settings(this.settings)
                         .build());
         this.scanFileProcessor = Objects.requireNonNullElseGet(scanFileProcessor, () ->
                 ScanFileProcessor.builder().winnowing(this.winnowing).scanApi(this.scanApi).build());
         this.wfpFileProcessor = Objects.requireNonNullElseGet(wfpFileProcessor, () -> WfpFileProcessor.builder()
                 .winnowing(this.winnowing)
                 .build());
-        this.settings = Objects.requireNonNullElseGet(settings, () -> ScanossSettings.builder().build());
         this.postProcessor = Objects.requireNonNullElseGet(postProcessor, () ->
                 ScannerPostProcessor.builder().build());
 

src/main/java/com/scanoss/Winnowing.java

@@ -80,6 +80,10 @@ public class Winnowing {
     @Builder.Default
     private int snippetLimit = MAX_LONG_LINE_CHARS; // Enable limiting of size of a single line of snippet generation
     @Builder.Default
+    private boolean skipHeaders = false; // Skip license headers, comments and imports at the beginning of files
+    @Builder.Default
+    private int skipHeadersLimit = 0; // Maximum number of header lines to skip (0 = auto-detect)
+    @Builder.Default
     private Map<String, String> obfuscationMap = new ConcurrentHashMap<>();
 
     /**
@@ -168,6 +172,12 @@ public String wfpForContents(@NonNull String filename, Boolean binFile, byte[] c
             wfpBuilder.append(String.format("hpsm=%s\n", Hpsm.calcHpsm(contents)));
         }
 
+        int skipLines = 0;
+        if (this.skipHeaders) {
+            skipLines = detectHeaderLines(fileContents, this.skipHeadersLimit);
+            log.trace("Skipping {} header lines for snippet generation: {}", skipLines, filename);
+        }
+
         String gram = "";
         List<Long> window = new ArrayList<>();
         char normalized;
@@ -183,7 +193,7 @@ public String wfpForContents(@NonNull String filename, Boolean binFile, byte[] c
             } else {
                 normalized = WinnowingUtils.normalize(c);
             }
-            if (normalized > 0) {
+            if (normalized > 0 && line > skipLines) {
                 gram += normalized;
                 if (gram.length() >= ScanossConstants.GRAM) {
                     Long gramCRC32 = crc32c(gram);
@@ -312,6 +322,69 @@ private Boolean skipSnippets(@NonNull String filename, char[] contents) {
         return false;
     }
 
+    /**
+     * Detect the number of header lines at the beginning of a file.
+     * Header lines include license comment blocks, single-line comments,
+     * blank lines, and import/package statements.
+     *
+     * @param contents  file contents as char array
+     * @param maxLines  maximum number of header lines to detect (0 = no limit)
+     * @return number of header lines detected
+     */
+    int detectHeaderLines(char[] contents, int maxLines) {
+        int headerLines = 0;
+        boolean inBlockComment = false;
+        int lineStart = 0;
+
+        for (int i = 0; i <= contents.length; i++) {
+            if (i == contents.length || contents[i] == '\n') {
+                String line = new String(contents, lineStart, i - lineStart).trim();
+
+                if (inBlockComment) {
+                    headerLines++;
+                    if (line.contains("*/")) {
+                        inBlockComment = false;
+                    }
+                } else if (line.isEmpty()) {
+                    headerLines++;
+                } else if (line.startsWith("//") || line.startsWith("#!") || line.startsWith("# ")) {
+                    headerLines++;
+                } else if (line.startsWith("/*")) {
+                    headerLines++;
+                    if (!line.contains("*/")) {
+                        inBlockComment = true;
+                    }
+                } else if (line.startsWith("*") || line.startsWith("* ")) {
+                    headerLines++;
+                } else if (isImportOrPackageLine(line)) {
+                    headerLines++;
+                } else {
+                    break; // Non-header line found
+                }
+
+                if (maxLines > 0 && headerLines >= maxLines) {
+                    break;
+                }
+
+                lineStart = i + 1;
+            }
+        }
+
+        return headerLines;
+    }
+
+    /**
+     * Check if a line is an import or package declaration.
+     *
+     * @param line trimmed source line
+     * @return true if the line is an import/package/include statement
+     */
+    private boolean isImportOrPackageLine(String line) {
+        return line.startsWith("import ") || line.startsWith("package ") ||
+                line.startsWith("from ") || line.startsWith("#include ") ||
+                line.startsWith("using ") || line.startsWith("require ");
+    }
+
     /**
      * Try to detect if this is a text file or not
      *

src/main/java/com/scanoss/cli/ScanCommandLine.java

@@ -25,6 +25,7 @@
 import com.scanoss.Scanner;
 import com.scanoss.exceptions.ScannerException;
 import com.scanoss.exceptions.WinnowingException;
+import com.scanoss.settings.FileSnippet;
 import com.scanoss.settings.ScanossSettings;
 import com.scanoss.utils.JsonUtils;
 import com.scanoss.utils.ProxyUtils;
@@ -105,6 +106,27 @@ class ScanCommandLine implements Runnable {
     @picocli.CommandLine.Option(names = {"-H", "--hpsm"}, description = "Use High Precision Snippet Matching algorithm")
     private boolean enableHpsm = false;
 
+    @picocli.CommandLine.Option(names = {"--min-snippet-hits"}, description = "Minimum snippet hits required (0 = unset, uses server config)")
+    private int minSnippetHits = 0;
+
+    @picocli.CommandLine.Option(names = {"--min-snippet-lines"}, description = "Minimum snippet lines required (0 = unset, uses server config)")
+    private int minSnippetLines = 0;
+
+    @picocli.CommandLine.Option(names = {"--honour-file-exts"}, description = "Honour file extensions (true|false|unset)", arity = "1")
+    private String honourFileExts = null;
+
+    @picocli.CommandLine.Option(names = {"--ranking"}, description = "Enable/disable ranking (true|false|unset)", arity = "1")
+    private String ranking = null;
+
+    @picocli.CommandLine.Option(names = {"--ranking-threshold"}, description = "Ranking threshold value (-1 = unset, uses server config)")
+    private int rankingThreshold = -1;
+
+    @picocli.CommandLine.Option(names = {"--skip-headers"}, description = "Skip license headers, comments and imports at the beginning of files (applies locally)")
+    private boolean skipHeaders = false;
+
+    @picocli.CommandLine.Option(names = {"--skip-headers-limit"}, description = "Skip limit for license headers (0 = unset, applies locally)")
+    private int skipHeadersLimit = 0;
+
     @picocli.CommandLine.Parameters(arity = "1", description = "file/folder to scan")
     private String fileFolder;
 
@@ -133,11 +155,25 @@ public void run() {
             }
         }
 
+        // Load settings from scanoss.json if provided, otherwise use defaults
+        ScanossSettings settings = new ScanossSettings();
         if(settingsPath != null && !settingsPath.isEmpty()) {
             settings = ScanossSettings.createFromPath(Paths.get(settingsPath));
             if (settings == null) throw new RuntimeException("Error: Failed to read settings file");
             printMsg(err, String.format("Settings file read %s", settings));
         }
+        // Build file_snippet config from CLI arguments (lowest priority)
+        FileSnippet fileSnippetCLI =  FileSnippet.builder()
+                .minSnippetHits(minSnippetHits)
+                .minSnippetLines(minSnippetLines)
+                .rankingThreshold(rankingThreshold)
+                .skipHeaders(skipHeaders)
+                .skipHeadersLimit(skipHeadersLimit)
+                .rankingEnabled(parseTriStateBoolean(ranking))
+                .honourFileExts(parseTriStateBoolean(honourFileExts))
+                .build();
+        // Resolve: file_snippet from scanoss.json (highest priority) overrides CLI values
+        settings.getSettings().setFileSnippet(FileSnippet.resolve(fileSnippetCLI, settings.getSettings().getFileSnippet()));
 
 
         if (com.scanoss.cli.CommandLine.debug) {
@@ -166,7 +202,6 @@ public void run() {
                 .snippetLimit(snippetLimit).customCert(caCertPem).proxy(proxy).hpsm(enableHpsm)
                 .settings(settings).obfuscate(obfuscate)
                 .build();
-
         File f = new File(fileFolder);
         if (!f.exists()) {
             throw new RuntimeException(String.format("Error: File or folder does not exist: %s\n", fileFolder));
@@ -198,6 +233,19 @@ private String loadFileToString(@NonNull String filename) {
         }
     }
 
+    /**
+     * Parse a tri-state boolean string value.
+     *
+     * @param value the string value ("true", "false", "unset", or null)
+     * @return Boolean.TRUE, Boolean.FALSE, or null for unset
+     */
+    private static Boolean parseTriStateBoolean(String value) {
+        if (value == null || value.equalsIgnoreCase("unset")) {
+            return null;
+        }
+        return Boolean.parseBoolean(value);
+    }
+
     /**
      * Scan the specified file and output the results
      *
@@ -245,7 +293,7 @@ private void scanFolder(String folder) {
             if (CommandLine.debug) {
                 e.printStackTrace(err);
             }
-            throw new RuntimeException(String.format("Something went wrong while scanning %s.", folder));
+            throw new RuntimeException(String.format("Something went wrong while scanning %s.", folder), e);
         }
     }
 }

src/main/java/com/scanoss/rest/ScanApi.java

@@ -25,6 +25,7 @@
 import com.scanoss.dto.SbomLegacy;
 import com.scanoss.exceptions.ScanApiException;
 import com.scanoss.settings.Rule;
+import com.scanoss.settings.FileSnippet;
 import com.scanoss.settings.ScanossSettings;
 import com.scanoss.utils.JsonUtils;
 import com.scanoss.utils.PackageDetails;
@@ -36,6 +37,7 @@
 import okhttp3.tls.HandshakeCertificates;
 
 import java.io.IOException;
+import java.nio.charset.StandardCharsets;
 import java.io.InterruptedIOException;
 import java.net.Proxy;
 import java.time.Duration;
@@ -178,6 +180,32 @@ public String scan(String wfp, String context, int scanID) throws ScanApiExcepti
             data.put("type", "identify");
         }
 
+        // Add scan configuration parameters as base64-encoded JSON in scanoss-settings key
+        if (this.settings != null && this.settings.getSettings().getFileSnippet() != null) {
+            FileSnippet fileSnippet = this.settings.getSettings().getFileSnippet();
+            Map<String, Object> settingsMap = new LinkedHashMap<>();
+            if (fileSnippet.isMinSnippetHitsSet()) {
+                settingsMap.put("min_snippet_hits", fileSnippet.getMinSnippetHits());
+            }
+            if (fileSnippet.isMinSnippetLinesSet()) {
+                settingsMap.put("min_snippet_lines", fileSnippet.getMinSnippetLines());
+            }
+            if (fileSnippet.isHonourFileExtsSet()) {
+                settingsMap.put("honour_file_exts", fileSnippet.getHonourFileExts());
+            }
+            if (fileSnippet.isRankingEnabledSet()) {
+                settingsMap.put("ranking_enabled", fileSnippet.getRankingEnabled());
+            }
+            if (fileSnippet.isRankingThresholdSet()) {
+                settingsMap.put("ranking_threshold", fileSnippet.getRankingThreshold());
+            }
+            if (!settingsMap.isEmpty()) {
+                String json = JsonUtils.toJson(settingsMap);
+                log.debug("scanoss settings:" + json);
+                String encoded = Base64.getEncoder().encodeToString(json.getBytes(StandardCharsets.UTF_8));
+                headers.put("scanoss-settings", encoded);
+            }
+        }
 
         Request request;  // Create multipart request
         try {