Expose repository scanner API

README.md

@@ -1,6 +1,7 @@
 # licenses
 
-Go library for matching license text against ScanCode's license rule corpus.
+Go library and command for matching license text and scanning repositories
+against ScanCode's license rule corpus.
 
 The corpus is embedded in the package. Matching needs no network access, cgo,
 or Python.
@@ -117,6 +118,25 @@
 }
 ```
 
+Scan a file or directory with the same matcher:
+
+```go
+options := licenses.DefaultScanOptions()
+options.IncludeLegalFiles = true
+report, err := licenses.ScanRepository(ctx, matcher, ".", options)
+if err != nil {
+	return err
+}
+
+for _, file := range report.Files {
+	fmt.Println(file.Path, file.Roles, file.Text)
+}
+```
+
+`IncludeLegalFiles` retains recognized license and notice files when the corpus
+does not produce a match. It also includes their complete text decoded to
+UTF-8.
+
 Matching uses normalized whole-text hashes, exact token sequences, and
 `SPDX-License-Identifier` tag lines. It does not use fuzzy or sequence
 matching, so edits within a license text can prevent a match.

cmd/licenses/licensee_comparison_test.go

@@ -1,3 +1,3 @@
 package main
 
 import (
@@ -199,7 +199,7 @@
 	if strings.Contains(cleaned, "/") {
 		return false
 	}
-	if isLegalFile(filePath) {
+	if len(licenses.LegalFileRoles(filePath)) != 0 {
 		return true
 	}
 	name := strings.ToLower(pathpkg.Base(cleaned))

cmd/licenses/main_test.go

@@ -1,3 +1,3 @@
 package main
 
 import (
@@ -65,6 +65,9 @@
 	if err := json.Unmarshal(stdout.Bytes(), &report); err != nil {
 		t.Fatalf("decode output: %v\n%s", err, stdout.String())
 	}
+	if strings.Contains(stdout.String(), `"text":`) {
+		t.Errorf("default JSON contains legal file text:\n%s", stdout.String())
+	}
 	if report.Root != "../../LICENSE" {
 		t.Errorf("root = %q, want ../../LICENSE", report.Root)
 	}