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.*;
@@ -104,6 +105,8 @@ public class Scanner {
     private final ScanFileProcessor scanFileProcessor;
     private final WfpFileProcessor wfpFileProcessor;
     private final ScanossSettings settings;
+    private final FileSnippet cliFileSnippet; // CLI-provided scan config (lowest priority)
+    private final FileSnippet fileSnippet; // Resolved scan config (after priority merge)
     private final ScannerPostProcessor postProcessor;
     private final FilterConfig filterConfig;
     private Predicate<Path> fileFilter;
@@ -116,7 +119,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, FileSnippet cliFileSnippet, FileSnippet fileSnippet,
+                    ScannerPostProcessor postProcessor, FilterConfig filterConfig,
                     Predicate<Path> fileFilter,
                     Predicate<Path> folderFilter
     ) {
@@ -137,20 +141,27 @@ 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());
+        this.cliFileSnippet = cliFileSnippet;
+        // Resolve scan config: file_snippet (highest) > CLI (lowest)
+        this.fileSnippet = this.settings.getResolvedScanConfig(
+                Objects.requireNonNullElseGet(cliFileSnippet, () -> FileSnippet.builder().build()));
         this.winnowing = Objects.requireNonNullElseGet(winnowing, () ->
                 Winnowing.builder().skipSnippets(skipSnippets).allExtensions(allExtensions).obfuscate(obfuscate)
                         .hpsm(hpsm).snippetLimit(snippetLimit)
+                        .skipHeaders(this.fileSnippet.getSkipHeaders() != null && this.fileSnippet.getSkipHeaders())
+                        .skipHeadersLimit(this.fileSnippet.getSkipHeadersLimit() != null ? this.fileSnippet.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)
+                        .fileSnippet(this.fileSnippet)
                         .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;
 
@@ -160,13 +182,13 @@ public void run() {
                 printMsg(err, String.format("Using flags %s", scanFlags));
             }
         }
+        FileSnippet cliFileSnippet = buildCliScanConfig();
         scanner = Scanner.builder().skipSnippets(skipSnippets).allFolders(allFolders).allExtensions(allExtensions)
                 .hiddenFilesFolders(allHidden).numThreads(numThreads).url(apiUrl).apiKey(apiKey)
                 .retryLimit(retryLimit).timeout(Duration.ofSeconds(timeoutLimit)).scanFlags(scanFlags)
                 .snippetLimit(snippetLimit).customCert(caCertPem).proxy(proxy).hpsm(enableHpsm)
-                .settings(settings).obfuscate(obfuscate)
+                .settings(settings).obfuscate(obfuscate).cliFileSnippet(cliFileSnippet)
                 .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 +220,38 @@ private String loadFileToString(@NonNull String filename) {
         }
     }
 
+    /**
+     * Build a ScanConfig from CLI arguments.
+     *
+     * @return ScanConfig populated with CLI-provided values
+     */
+    private FileSnippet buildCliScanConfig() {
+        FileSnippet.FileSnippetBuilder builder = FileSnippet.builder()
+                .minSnippetHits(minSnippetHits)
+                .minSnippetLines(minSnippetLines)
+                .rankingThreshold(rankingThreshold)
+                .skipHeaders(skipHeaders)
+                .skipHeadersLimit(skipHeadersLimit);
+
+        builder.honourFileExts(parseTriStateBoolean(honourFileExts));
+        builder.rankingEnabled(parseTriStateBoolean(ranking));
+
+        return builder.build();
+    }
+
+    /**
+     * 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 +299,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;
@@ -72,12 +74,14 @@ public class ScanApi {
     private Proxy proxy; // Proxy configuration
     private String baseUrl; // SCANOSS base API URI (to used instead of url)
     private ScanossSettings settings;
+    private FileSnippet fileSnippet; // Resolved scan configuration parameters
     @SuppressWarnings("unused")
     private ScanApi(String scanType, Duration timeout, Integer retryLimit, String url, String apiKey, String flags,
                     String sbomType, String sbom,
                     OkHttpClient okHttpClient, Map<String, String> headers, String customCert,
-                    Proxy proxy, String baseUrl, ScanossSettings settings) {
+                    Proxy proxy, String baseUrl, ScanossSettings settings, FileSnippet fileSnippet) {
         this.settings = settings;
+        this.fileSnippet = fileSnippet;
         this.scanType = scanType;
         this.timeout = timeout;
         this.retryLimit = retryLimit;
@@ -178,6 +182,30 @@ 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 (fileSnippet != null) {
+            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);
+                String encoded = Base64.getEncoder().encodeToString(json.getBytes(StandardCharsets.UTF_8));
+                headers.put("scanoss-settings", encoded);
+            }
+        }
 
         Request request;  // Create multipart request
         try {