Skip to content

Commit a4f0e1b

Browse files
pmonkspmonks
authored
Merge pull request #55 from pmonks/dev
Release 2.0.318
2 parents e422eaa + 1d38b86 commit a4f0e1b

25 files changed

+961
-549
lines changed

‎.github/workflows/vulnerabilities.yml

+18-4
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,25 @@
11
name: vulnerabilities
22
on:
33
# Don't require this on push or pull_request, or it'll block releases even for minor vulnerabilities
4-
# Note: scheduled actions only run on the default branch - see https://github.com/orgs/community/discussions/38800
4+
# push:
5+
# pull_request:
56
schedule:
67
- cron: '0 2 * * 2' # Every Tuesday at 2am
78

89
jobs:
10+
skip_check:
11+
runs-on: ubuntu-latest
12+
outputs:
13+
should_skip: ${{ steps.skip_check.outputs.should_skip }}
14+
steps:
15+
- id: skip_check
16+
uses: fkirc/skip-duplicate-actions@master
17+
918
vulnerabilities:
19+
needs: skip_check
20+
if: ${{ needs.skip_check.outputs.should_skip != 'true' }}
21+
runs-on: ubuntu-latest
22+
1023
steps:
1124
- uses: actions/checkout@v4
1225
with:
@@ -28,11 +41,12 @@ jobs:
2841
key: ${{ runner.os }}-${{ hashFiles('**/deps.edn') }}
2942

3043
- name: Run NVD vulnerabilities check
44+
env:
45+
NVD_API_TOKEN: ${{ secrets.NVD_API_TOKEN }}
3146
run: clojure -Srepro -J-Dclojure.main.report=stderr -T:build nvd
3247

33-
- name: Deploy NVD vulnerability report
34-
# if: ${{ ( success() || failure() ) && github.ref == 'refs/heads/release' }} # Only deploy report from release branch, and regardless of whether the job succeeded or failed
35-
if: ${{ ( success() || failure() ) }}
48+
- name: Deploy NVD vulnerability report (dev branch only) # Because GitHub is idiotic and only supports timed jobs on the default branch (dev)
49+
if: ${{ ( success() || failure() ) && github.ref == 'refs/heads/dev' }} # Deploy report regardless of whether the job succeeded or failed
3650
uses: peaceiris/actions-gh-pages@v4
3751
with:
3852
github_token: ${{ secrets.GITHUB_TOKEN }}

‎README.md

+7-5
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
| | | |
22
|---:|:---:|:---:|
33
| [**release**](https://github.com/pmonks/lice-comb/tree/release) | [![CI](https://github.com/pmonks/lice-comb/actions/workflows/ci.yml/badge.svg?branch=release)](https://github.com/pmonks/lice-comb/actions?query=workflow%3ACI+branch%3Arelease) | [![Dependencies](https://github.com/pmonks/lice-comb/actions/workflows/dependencies.yml/badge.svg?branch=release)](https://github.com/pmonks/lice-comb/actions?query=workflow%3Adependencies+branch%3Arelease) |
4-
| [**dev**](https://github.com/pmonks/lice-comb/tree/dev) | [![CI](https://github.com/pmonks/lice-comb/workflows/CI/badge.svg?branch=dev)](https://github.com/pmonks/lice-comb/actions?query=workflow%3ACI+branch%3Adev) | [![Dependencies](https://github.com/pmonks/lice-comb/actions/workflows/dependencies.yml/badge.svg?branch=dev)](https://github.com/pmonks/lice-comb/actions?query=workflow%3Adependencies+branch%3Adev) |
4+
| [**dev**](https://github.com/pmonks/lice-comb/tree/dev) | [![CI](https://github.com/pmonks/lice-comb/actions/workflows/ci.yml/badge.svg?branch=dev)](https://github.com/pmonks/lice-comb/actions?query=workflow%3ACI+branch%3Adev) | [![Dependencies](https://github.com/pmonks/lice-comb/actions/workflows/dependencies.yml/badge.svg?branch=dev)](https://github.com/pmonks/lice-comb/actions?query=workflow%3Adependencies+branch%3Adev) |
55

66
[![Latest Version](https://img.shields.io/clojars/v/com.github.pmonks/lice-comb)](https://clojars.org/com.github.pmonks/lice-comb/) [![License](https://img.shields.io/github/license/pmonks/lice-comb.svg)](https://github.com/pmonks/lice-comb/blob/release/LICENSE) [![Open Issues](https://img.shields.io/github/issues/pmonks/lice-comb.svg)](https://github.com/pmonks/lice-comb/issues) [![Vulnerabilities](https://github.com/pmonks/lice-comb/actions/workflows/vulnerabilities.yml/badge.svg)](https://pmonks.github.io/lice-comb/nvd/dependency-check-report.html)
77

@@ -83,9 +83,10 @@ $ deps-try com.github.pmonks/lice-comb
8383
(lcmvn/gav->expressions "commons-io" "commons-io" "2.15.0")
8484
;=> #{"Apache-2.0"}
8585

86-
; Note: this looks up and uses only the latest version of the given project
86+
; Note: this looks up and uses the latest version of the given project (1.5.0-b01 at the time of
87+
; writing), so the results you get may be different to what you see here
8788
(lcmvn/gav->expressions "javax.mail" "mail")
88-
;=> #{"GPL-2.0-only WITH Classpath-exception-2.0" "CDDL-1.1"}
89+
;=> #{"CDDL-1.1 OR GPL-2.0-only WITH Classpath-exception-2.0"}
8990

9091
(lcmvn/pom->expressions (str (System/getProperty "user.home") "/.m2/repository/org/clojure/clojure/1.11.2/clojure-1.11.2.pom"))
9192
;=> #{"EPL-1.0"}
@@ -125,7 +126,8 @@ $ deps-try com.github.pmonks/lice-comb
125126
; {:id "Classpath-exception-2.0", :type :concluded, :confidence :low, :strategy :regex-matching,
126127
; :source ("GNU Public License 2.0 or later w/ the GNU Classpath Exception"
127128
; "the GNU Classpath Exception"
128-
; "Classpath Exception")})}
129+
; "Classpath Exception"),
130+
; :confidence-explanations #{:missing-version}})}
129131

130132
(lcmvn/pom->expressions-info "https://repo.clojars.org/canvas/canvas/0.1.6/canvas-0.1.6.pom")
131133
;=> {"EPL-2.0 OR GPL-2.0-or-later WITH Classpath-exception-2.0"
@@ -138,7 +140,7 @@ $ deps-try com.github.pmonks/lice-comb
138140
;; Pretty print expressions-info
139141
(require '[lice-comb.utils :as lcu])
140142

141-
(println (lcu/expressions-info->string (lcd/dep->expressions-info ['com.amazonaws/aws-java-sdk-s3 {:deps/manifest :mvn :mvn/version "1.12.129"}])))
143+
(println (lcu/expressions-info->string (lcmvn/gav->expressions-info "com.amazonaws" "aws-java-sdk-s3" "1.12.129")))
142144
;=> Apache-2.0:
143145
; Concluded
144146
; Confidence: high

‎deps.edn

+4-4
Original file line numberDiff line numberDiff line change
@@ -19,16 +19,16 @@
1919
{:paths ["src" "resources"]
2020
:deps
2121
{org.clojure/tools.logging {:mvn/version "1.3.0"}
22-
commons-validator/commons-validator {:mvn/version "1.8.0"}
22+
commons-validator/commons-validator {:mvn/version "1.9.0"}
2323
org.clojure/data.xml {:mvn/version "0.2.0-alpha9"}
2424
clj-xml-validation/clj-xml-validation {:mvn/version "1.0.2"}
2525
tolitius/xml-in {:mvn/version "0.1.1"}
2626
hato/hato {:mvn/version "0.9.0"}
27-
dev.weavejester/medley {:mvn/version "1.7.0"}
27+
dev.weavejester/medley {:mvn/version "1.8.0"}
2828
miikka/clj-base62 {:mvn/version "0.1.1"}
29-
com.github.pmonks/clj-spdx {:mvn/version "1.0.152"}
29+
com.github.pmonks/clj-spdx {:mvn/version "1.0.174"}
3030
com.github.pmonks/rencg {:mvn/version "1.0.51"}
31-
com.github.pmonks/embroidery {:mvn/version "0.1.20"}}
31+
com.github.pmonks/embroidery {:mvn/version "1.0.41"}}
3232
:aliases
3333
{:build {:deps {com.github.pmonks/pbr {:mvn/version "RELEASE"}}
3434
:ns-default pbr.build}}}

‎doc/overview.md

+74
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# Overview
2+
3+
Most of the namespaces in this library provide two variants of every license detection function:
4+
5+
1. A 'simple' version that returns a set of SPDX expressions (`String`s)
6+
2. An 'info' version that returns an 'expressions-info map' containing metadata on how the determination was made (including confidence & source information)
7+
8+
If all you're interested in are the license expressions themselves, the 'simple' variant is what you're after (e.g. [[lice-comb.matching/name->expressions]]). However in choosing to use these 'simple' variants you're placing full faith & confidence that lice-comb has done the right thing. Given that license matching is a messy business, you may wish to have better visibility into how lice-comb made a particular determination, and that can be done with the 'info' variants (e.g. [[lice-comb.matching/name->expressions-info]]).
9+
10+
## expressions-info map
11+
12+
The 'info' variants all return an 'expressions-info' map, which has this structure:
13+
14+
* key: an SPDX expression (`String`)
15+
* value: a sequence of 'expression-info' maps
16+
17+
## expression-info map
18+
19+
Each expression-info map in the sequence of values has this structure:
20+
21+
* `:id` (`String`, optional):
22+
The portion of the SPDX expression that this info map refers to (usually, though not always, a single SPDX identifier).
23+
* `:type` (either `:declared` or `:concluded`, mandatory):
24+
Whether this identifier was unambiguously declared within the input or was instead concluded by lice-comb (see [the SPDX FAQ](https://wiki.spdx.org/view/SPDX_FAQ) for more detail on the definition of these two terms).
25+
* `:confidence` (one of: `:high`, `:medium`, `:low`, only provided when `:type` = `:concluded`):
26+
Indicates the approximate confidence lice-comb has in its conclusions for this particular SPDX identifier.
27+
* `:strategy` (a keyword, mandatory):
28+
The strategy lice-comb used to determine this particular SPDX identifier. See [[lice-comb.utils/strategy->string]] for an up-to-date list of all possible values.
29+
* `:source` (a sequence of `String`s):
30+
The list of sources used to arrive at this portion of the SPDX expression, starting from the most general (the input) through to the most specific (the smallest subset of the input that was used to make this determination. These may include dependencies expressed in Leiningen or tools.deps format, Maven GAVs, file paths, URIs, XML tags, text fragments, and other string data, and are intended for human, rather than programmatic, consumption.
31+
32+
## Example
33+
34+
For example, this code:
35+
36+
```clojure
37+
(require '[lice-comb.maven :as lcmvn])
38+
(lcmvn/gav->expressions-info "javax.mail" "javax.mail-api" "1.6.2")
39+
```
40+
41+
results in this expressions-info map (pretty printed for clarity):
42+
43+
```clojure
44+
{"GPL-2.0-or-later"
45+
({:id "GPL-2.0-or-later",
46+
:type :concluded,
47+
:confidence :medium,
48+
:strategy :regex-matching,
49+
:source ("https://repo1.maven.org/maven2/javax/mail/javax.mail-api/1.6.2/javax.mail-api-1.6.2.pom"
50+
"https://repo1.maven.org/maven2/com/sun/mail/all/1.6.2/all-1.6.2.pom"
51+
"<licenses><license><name>"
52+
"CDDL/GPLv2+CE"
53+
"GPLv2+")}),
54+
"CDDL-1.1"
55+
({:id "CDDL-1.1",
56+
:type :concluded,
57+
:confidence :low,
58+
:strategy :regex-matching,
59+
:source ("https://repo1.maven.org/maven2/javax/mail/javax.mail-api/1.6.2/javax.mail-api-1.6.2.pom"
60+
"https://repo1.maven.org/maven2/com/sun/mail/all/1.6.2/all-1.6.2.pom"
61+
"<licenses><license><name>"
62+
"CDDL/GPLv2+CE"
63+
"CDDL")})}
64+
```
65+
66+
A key insight that the expressions-info map tells us in this case is that the `javax.mail/javax.mail-api@1.6.2` artifact doesn't declare which version of the CDDL it uses, and lice-comb has _inferred_ the latest (`CDDL-1.1`), and in doing so reduced its confidence to "low". This important insight is not apparent when the `simple` variant of the function is used instead:
67+
68+
```clojure
69+
(lcmvn/gav->expressions "javax.mail" "javax.mail-api" "1.6.2")
70+
71+
#{"CDDL-1.1" "GPL-2.0-or-later"}
72+
```
73+
74+
[Back to GitHub](https://github.com/pmonks/lice-comb)

‎pbr.clj

+3-1
Original file line numberDiff line numberDiff line change
@@ -31,4 +31,6 @@
3131
:developers [:developer {:id "pmonks" :name "Peter Monks" :email "pmonks+lice-comb@gmail.com"}]
3232
:scm {:url "https://github.com/pmonks/lice-comb" :connection "scm:git:git://github.com/pmonks/lice-comb.git" :developer-connection "scm:git:ssh://git@github.com/pmonks/lice-comb.git"}
3333
:issue-management {:system "github" :url "https://github.com/pmonks/lice-comb/issues"}}
34-
:codox {:namespaces ['lice-comb.deps 'lice-comb.files 'lice-comb.lein 'lice-comb.matching 'lice-comb.maven 'lice-comb.utils]}))
34+
:codox {:namespaces ['lice-comb.deps 'lice-comb.files 'lice-comb.lein 'lice-comb.matching 'lice-comb.maven 'lice-comb.utils]
35+
:metadata {:doc/format :markdown}
36+
:doc-files ["doc/overview.md"]}))

‎src/lice_comb/deps.clj

+20-21
Original file line numberDiff line numberDiff line change
@@ -71,9 +71,8 @@
7171
(:paths info))))))))
7272

7373
(defmulti dep->expressions-info
74-
"Returns an expressions-info map for the given tools.dep dep (a MapEntry or
75-
two-element vector of `['group-id/artifact-id dep-info]`), or nil if no
76-
expressions were found."
74+
"Returns an expressions-info map for `dep` (a `MapEntry` or two-element vector
75+
of `['group-id/artifact-id dep-info]`), or `nil` if no expressions were found."
7776
{:arglists '([[ga info :as dep]])}
7877
(fn [[_ info]] (:deps/manifest info)))
7978

@@ -106,9 +105,8 @@
106105
{:dep dep})))
107106

108107
(defn dep->expressions
109-
"Returns a set of SPDX expressions (Strings) for the given tools.dep dep (a
110-
MapEntry or two-element vector of `['group-id/artifact-id dep-info-map]`), or
111-
nil if no expressions were found."
108+
"Returns a set of SPDX expressions (`String`s) for `dep`. See
109+
[[dep->expressions-info]] for details."
112110
[dep]
113111
(some-> (dep->expressions-info dep)
114112
keys
@@ -129,12 +127,12 @@
129127
deps))))
130128

131129
(defn dep->pom-uri
132-
"Returns a java.net.URI that points to the pom for the given tools.dep dep (a
133-
MapEntry or two-element vector of `['group-id/artifact-id dep-info]`), or nil if
134-
the dep is not a Maven dep, or a POM could not be found. The returned URI is
135-
guaranteed to be resolvable - either to a file that exists in the local Maven
136-
cache, or to an HTTP-accessible resource on a remote Maven repository (i.e.
137-
Maven Central or Clojars) that resolves."
130+
"Returns a `URI` that points to the pom for `dep` (a `MapEntry` or two-element
131+
vector of `['group-id/artifact-id dep-info]`), or `nil` if `dep` is not a
132+
Maven dep, or a POM could not be found for it. When non-`nil`, the returned
133+
URI is guaranteed to be resolvable - either to a file that exists in the local
134+
Maven cache, or to an HTTP-accessible resource on a remote Maven artifact
135+
repository (e.g. Maven Central or Clojars)."
138136
[dep]
139137
(when (and dep
140138
(= :mvn (:deps/manifest (second dep))))
@@ -144,10 +142,9 @@
144142
(lcmvn/gav->pom-uri group-id artifact-id version))))
145143

146144
(defmulti dep->locations
147-
"Returns a sequence of Strings representing locations that may be searched
148-
for license information for the given tools.dep dep (a MapEntry or two-element
149-
vector of `['group-id/artifact-id dep-info]`),or nil if no locations were
150-
found."
145+
"Returns a sequence of `String`s representing locations that may be searched
146+
for license information for `dep` (a `MapEntry` or two-element vector of
147+
`['group-id/artifact-id dep-info]`), or `nil` if no locations were found."
151148
{:arglists '([[ga info :as dep]])}
152149
(fn [[_ info]] (:deps/manifest info)))
153150

@@ -172,9 +169,9 @@
172169
{:dep dep})))
173170

174171
(defmulti dep->version
175-
"Returns the version (as a String) for the given tools.dep dep (a MapEntry or
176-
two-element vector of `['group-id/artifact-id dep-info]`),or nil if no version
177-
was found."
172+
"Returns the Maven version (as a `String`) for `dep` (a `MapEntry` or
173+
two-element vector of `['group-id/artifact-id dep-info]`), or `nil` if no
174+
version was found."
178175
{:arglists '([[ga info :as dep]])}
179176
(fn [[_ info]] (:deps/manifest info)))
180177

@@ -198,9 +195,11 @@
198195

199196
(defn init!
200197
"Initialises this namespace upon first call (and does nothing on subsequent
201-
calls), returning nil. Consumers of this namespace are not required to call
198+
calls), returning `nil`. Consumers of this namespace are not required to call
202199
this fn, as initialisation will occur implicitly anyway; it is provided to
203-
allow explicit control of the cost of initialisation to callers who need it."
200+
allow explicit control of the cost of initialisation to callers who need it.
201+
202+
Note: this method may have a substantial performance cost."
204203
[]
205204
(lcmvn/init!)
206205
(lcf/init!)

0 commit comments

Comments
 (0)