Update to v1.1.0

HubTou · Mar 3, 2024 · cd2d1a0 · cd2d1a0
1 parent 3500586
commit cd2d1a0
Show file tree

Hide file tree

Showing 6 changed files with 365 additions and 88 deletions.
diff --git a/README.md b/README.md
@@ -5,6 +5,7 @@ use one of the following commands, depending on if you want only this tool, the
 ```
 pip install pnu-portstreelint
 pip install PNU
+pip install 'PNU[freebsd]' # if you use a platform other than FreeBSD
 pip install pytnix
 ```
 
@@ -27,6 +28,7 @@ portstreelint - FreeBSD ports tree lint
 \[--unchanged NUM\]
 \[--check-host|-h\]
 \[--check-url|-u\]
+\[--output|-o FILE\]
 \[--debug\]
 \[--info\]
 \[--version\]
@@ -70,7 +72,7 @@ The checks list includes:
 * URL ending INDEX:description-file
 * INDEX:description-file content same as INDEX:comment
 * INDEX:description-file content no longer than INDEX:comment
-* Nonexistent pkg-plist, Makefile:PLIST_FILES/PLIST/PLIST_SUB (info)
+* Nonexistent pkg-plist, Makefile:PLIST_FILES/PLIST/PLIST_SUB (debug)
 * Makefile:PLIST_FILES abuse (warning)
 * INDEX:maintainer different from Makefile:MAINTAINER
 * Unofficial categories (warning)
@@ -79,17 +81,25 @@ The checks list includes:
 * Unresolvable INDEX:www-site (optional)
 * Unaccessible INDEX:www-site (optional)
 * INDEX:www-site different from Makefile:WWW
-* Ports marked as BROKEN, FORBIDDEN or DEPRECATED
-* Ports marked as IGNORE (warning, unreliable)
-* Ports marked as BROKEN, FORBIDDEN or DEPRECATED for too long
+* Ports marked as BROKEN, DEPRECATED, FORBIDDEN, IGNORE, RESTRICTED (info)
+* Ports marked with an EXPIRATION_DATE (warning)
+* Ports marked as BROKEN, FORBIDDEN or DEPRECATED for too long (warning)
 * Ports unchanged for a long time (info)
+* Makefile:PORTVERSION and Makefile:DISTVERSION used simultaneously
+* VuXML vulnerabilities for the current port versions (warning)
 
 It's possible to change the default values for PLIST_FILES abuse,
 BROKEN_since, DEPRECATED_since, FORBIDDEN_since and Unchanged_since
 with the *--plist*, *--broken*, *--deprecated*, *--forbidden* and
 *--unchanged* options, followed by a number of files for the first
 one and a number of days for the others.
 
+Finally, there's a *--output|-o* option to generate a CSV delimited
+file with the per-maintainer findings to a specified filename. This
+allows for automated processing of the results, such as, for example,
+sending warning emails, storing results and displaying only diffs
+since previous run...
+
 ### OPTIONS
 Options | Use
 ------- | ---
@@ -105,12 +115,16 @@ Options | Use
 --unchanged NUM|Set Unchanged since to NUM days
 --check-host\|-h|Enable checking hostname resolution (long!)
 --check-url\|-u|Enable checking URL (very long!)
+--output\|-o|Enable per-maintainer CSV output to FILE
 --debug|Enable logging at debug level
 --info|Enable logging at info level
 --version|Print version and exit
 --help\|-?|Print usage and this help message and exit
 --|Options processing terminator
 
+## ENVIRONMENT
+The *PORTSTREELINT_DEBUG* environment variable can be set to any value to enable debug mode.
+
 ## FILES
 The whole port tree under /usr/ports
 - as root, get the last version with "portsnap fetch update"
@@ -132,6 +146,14 @@ Results for this example are available there:
 * [stdout output](https://www.frbsd.org/xch/stdout.txt),
 * [stderr output](https://www.frbsd.org/xch/stderr.txt) for details.
 
+To analyze the full port tree in the background and generate a CSV
+file, do:
+```Shell
+$ nohup portstreelint -huo csv_results.txt > /dev/null 2>&1 &
+```
+Results for this example are available there:
+* [CSV output](https://www.frbsd.org/xch/csv_results.txt) for machine processing.
+
 To analyze the ports of a specific maintainer identified by id@domain, do:
 ```Shell
 $ portstreelint --info -m id@domain
@@ -164,3 +186,14 @@ It is available under the [3-clause BSD license](https://opensource.org/licenses
 
 ## AUTHORS
 [Hubert Tournier](https://github.com/HubTou)
+
+## CAVEATS
+The IGNORE mark check is not reliable because this tool doesn't parse
+the ports' Makefiles, but just loads their variables without regard to
+the conditional tests that may surround them.
+
+PORTREVISION is not taken into account in the vulnerabilities check
+which may leads to reporting false positives. The ports using exotic
+versioning schemes will also be skipped because the library we use
+for version comparisons is geared toward Python ports and limited
+for this usage.
diff --git a/TODO.md b/TODO.md
@@ -1,26 +1,31 @@
 # portstreelint TODOLIST
 
 ## Planned changes
-* Checking reported vulnerabilities with my [vuxml](https://github.com/HubTou/vuxml) library
+* Next version: splitting library.py code into multiple files for modularity
+* Version +2: checking distfiles availability
 
 ## Probable evolutions
-* Checking distfiles availability
-* Configuration file
+
+## Possible evolutions
+* Providing a mechanism to keep track of external events
+  * For example, the INDEX:www-site being unavailable since date X
+* Having a configuration file
   * Limits setting
   * Checks disabling
   * Exclusion of ports, maintainers, categories
-* Other output formats (JSON, XML, CSV ?)
-
-## Possible evolutions
+  * Correction of false positives
 * Checking the existence of domains in maintainer's email addresses
 * Checking the depends fields (extract/patch/fetch/build/run):
   * between the Index and the Makefiles
   * against the existence of the dependencies
 * Other Makefiles related checks
-* Adding an option to notice port maintainers by email (but I don't want to harrass them...)
 
 ## Unprobable evolutions
-* Checking reported vulnerabilities in dependencies
-* Checking unavailable ports in dependencies
+* Adding an option to notice port maintainers by email => will be better done by a wrapping script using the per-maintainer output
+* Side functionalities => not the direct purpose of this tool
+  * Checking reported vulnerabilities in dependencies
+  * Checking unavailable ports in dependencies
+* Checking ports that could be flavourized => no ideas for implementation (yet!)
+  * See https://lists.freebsd.org/archives/freebsd-ports/2024-March/005597.html
 
 Feel free to submit your own ideas!
diff --git a/man/portstreelint.8 b/man/portstreelint.8
@@ -1,4 +1,4 @@
-.Dd March 1, 2024
+.Dd March 3, 2024
 .Dt portstreelint 8
 .Os
 .Sh NAME
@@ -18,6 +18,7 @@
 .Op Fl \\-unchanged Ar NUM
 .Op Fl \\-check\-host|\-h
 .Op Fl \\-check\-url|\-u
+.Op Fl \\-output|\-o Ar FILE
 .Op Fl \-debug
 .Op Fl \-info
 .Op Fl \-version
@@ -87,7 +88,7 @@ INDEX:description\-file content same as INDEX:comment
 .It
 INDEX:description\-file content no longer than INDEX:comment
 .It
-Nonexistent pkg\-plist, Makefile:PLIST_FILES/PLIST/PLIST_SUB (info)
+Nonexistent pkg\-plist, Makefile:PLIST_FILES/PLIST/PLIST_SUB (debug)
 .It
 Makefile:PLIST_FILES abuse (warning)
 .It
@@ -105,13 +106,17 @@ Unaccessible INDEX:www\-site (optional)
 .It
 INDEX:www\-site different from Makefile:WWW
 .It
-Ports marked as BROKEN, FORBIDDEN or DEPRECATED
+Ports marked as BROKEN, DEPRECATED, FORBIDDEN, IGNORE, RESTRICTED (info)
 .It
-Ports marked as IGNORE (warning, unreliable)
+Ports marked with an EXPIRATION_DATE (warning)
 .It
-Ports marked as BROKEN, FORBIDDEN or DEPRECATED for too long
+Ports marked as BROKEN, FORBIDDEN or DEPRECATED for too long (warning)
 .It
 Ports unchanged for a long time (info)
+.It
+Makefile:PORTVERSION and Makefile:DISTVERSION used simultaneously
+.It
+VuXML vulnerabilities for the current port versions (warning)
 .El
 .Pp
 It's possible to change the default values for PLIST_FILES abuse,
@@ -125,6 +130,13 @@ and
 .Op Fl \-unchanged
 options, followed by a number of files for the first
 one and a number of days for the others.
+.Pp
+Finally, there's a
+.Op Fl \-output|\-o
+option to generate a CSV delimited file with the per\-maintainer
+findings to a specified filename. This allows for automated processing
+of the results, such as, for example, sending warning emails, storing
+results and displaying only diffs since previous run...
 .Ss OPTIONS
 .Op Fl \-show\-cat|\-C
 Show categories with ports count
@@ -162,6 +174,9 @@ Enable checking hostname resolution (long!)
 .Op Fl \-check\-url|\-u
 Enable checking URL (very long!)
 .Pp
+.Op Fl \-output|\-o
+Enable per\-maintainer CSV output to FILE
+.Pp
 .Op Fl \-debug
 Enable logging at debug level
 .Pp
@@ -176,15 +191,20 @@ Print usage and this help message and exit
 .Pp
 .Op Fl \-
 Options processing terminator
+.Sh ENVIRONMENT
+The
+.Ev PORTSTREELINT_DEBUG
+environment variable can be set to any value to enable debug mode.
 .Sh FILES
 The whole port tree under
 .Pa /usr/ports
 \- as root, get the last version with "portsnap fetch update"
 .Pp
 .Pa /usr/ports/INDEX\-xx
-\- where xx is the major version of FreeBSD that you are using (as I write this xx=14).
-As root, get the last version with "cd /usr/ports ; make fetchindex"
-or rebuild it from your port tree with "cd /usr/ports ; make index"
+\- where xx is the major version of FreeBSD that you are using
+(as I write this xx=14). As root, get the last version with
+"cd /usr/ports ; make fetchindex" or rebuild it from your port tree
+with "cd /usr/ports ; make index"
 .Sh EXIT STATUS
 .Ex -std portstreelint
 .Sh EXAMPLES
@@ -193,7 +213,14 @@ To analyze the full port tree (takes a long time!), do:
 $ nohup portstreelint \-\-info \-hu > stdout.txt 2> stderr.txt &
 .Ed
 .Pp
-To analyze the ports of a specific maintainer identified by id@domain, do:
+To analyze the full port tree in the background and generate a CSV
+file, do:
+.Bd -literal
+$ nohup portstreelint \-huo csv_results.txt > /dev/null 2>&1 &
+.Ed
+.Pp
+To analyze the ports of a specific maintainer identified by id@domain,
+do:
 .Bd -literal
 $ portstreelint \-\-info \-m id@domain
 .Ed
@@ -206,7 +233,8 @@ The
 .Nm
 utility is not a standard UNIX command.
 .Pp
-This implementation tries to follow the PEP 8 style guide for Python code.
+This implementation tries to follow the PEP 8 style guide for Python
+code.
 .Sh PORTABILITY
 None. Works only on FreeBSD, but who needs anything else?
 .Sh HISTORY
@@ -227,3 +255,13 @@ It is available under the 3\-clause BSD license.
 .Sh AUTHORS
 .An Hubert Tournier
 .Lk https://github.com/HubTou
+.Sh CAVEATS
+The IGNORE mark check is not reliable because this tool doesn't parse
+the ports' Makefiles, but just loads their variables without regard to
+the conditional tests that may surround them.
+.Pp
+PORTREVISION is not taken into account in the vulnerabilities check
+which may leads to reporting false positives. The ports using exotic
+versioning schemes will also be skipped because the library we use
+for version comparisons is geared toward Python ports and limited
+for this usage.
diff --git a/setup.cfg b/setup.cfg
@@ -3,7 +3,7 @@ name = pnu-portstreelint
 description = FreeBSD ports tree lint
 long_description = file: README.md
 long_description_content_type = text/markdown
-version = 1.0.1
+version = 1.1.0
 license = BSD 3-Clause License
 license_files = License
 author = Hubert Tournier
@@ -38,7 +38,7 @@ packages = find:
 python_requires = >=3.6
 install_requires =
     pnu-libpnu
-    pnu-vuxml
+    pnu-vuxml >= 1.0.1
 
 [options.packages.find]
 where = src