From daab9658f8657a8edb3a077c1e769ede62f6b993 Mon Sep 17 00:00:00 2001
From: Ed Santiago <santiago@redhat.com>
Date: Tue, 6 Apr 2021 09:08:50 -0600
Subject: [CI:DOCS] swagger-check: compare operations

Until now we've only compared operations when called with the
non-default --pedantic flag, because there were way too many
exceptions.

With the merge of #9944 the rules have become much cleaner.
Still not perfect, but it's now possible to have simple
general rules with a (semi-)manageable list of exceptions.

Signed-off-by: Ed Santiago <santiago@redhat.com>
---
 hack/swagger-check | 101 +++++++++++++++++++++++++++++++++++++----------------
 1 file changed, 71 insertions(+), 30 deletions(-)

(limited to 'hack')

diff --git a/hack/swagger-check b/hack/swagger-check
index f2e30cc33..646cbcb84 100755
--- a/hack/swagger-check
+++ b/hack/swagger-check
@@ -59,11 +59,6 @@ says 'libpod'.
 
 OPTIONS:
 
-  --pedantic     Compare operation names (the last part of swagger comment).
-                 There are far too many of these inconsistencies to allow us
-                 to enable this by default, but it still might be a useful
-                 check in some circumstances.
-
   -v, --verbose  show verbose progress indicators
   -n, --dry-run  make no actual changes
 
@@ -75,7 +70,6 @@ END_USAGE
 }
 
 # Command-line options.  Note that this operates directly on @ARGV !
-our $pedantic;
 our $debug   = 0;
 our $force   = 0;
 our $verbose = 0;
@@ -83,8 +77,6 @@ our $NOT     = '';              # print "blahing the blah$NOT\n" if $debug
 sub handle_opts {
     use Getopt::Long;
     GetOptions(
-        'pedantic'   => \$pedantic,
-
         'debug!'     => \$debug,
         'dry-run|n!' => sub { $NOT = ' [NOT]' },
         'force'      => \$force,
@@ -225,26 +217,14 @@ sub handle_handle {
     my $tag = ($endpoint =~ /(libpod)/ ? $1 : 'compat');
 
     #
-    # Determine the OPERATION. *** NOTE: This is mostly useless! ***
-    # In an ideal world the swagger comment would match actual function call;
-    # in reality there are over thirty mismatches. Use --pedantic to see.
+    # Determine the OPERATION. Done in a helper function because there
+    # are a lot of complicated special cases.
     #
-    my $operation = '';
-    if ($line =~ /(generic|handlers|compat)\.(\w+)/) {
-        $operation = lcfirst $2;
-        if ($endpoint =~ m!/libpod/! && $operation !~ /^libpod/) {
-            $operation = 'libpod' . ucfirst $operation;
-        }
-    }
-    elsif ($line =~ /(libpod)\.(\w+)/) {
-        $operation = "$1$2";
-    }
+    my $operation = operation_name($method, $endpoint);
 
     # Special case: the following endpoints all get a custom tag
     if ($endpoint =~ m!/(pods|manifests)/!) {
         $tag = $1;
-        $operation =~ s/^libpod//;
-        $operation = lcfirst $operation;
     }
 
     # Special case: anything related to 'events' gets a system tag
@@ -264,13 +244,6 @@ sub handle_handle {
 
     my $actual = $actual[0];
 
-    # By default, don't compare the operation: there are far too many
-    # mismatches here.
-    if (! $pedantic) {
-        $actual =~ s/\s+\S+\s*$//;
-        $expect =~ s/\s+\S+\s*$//;
-    }
-
     # (Ignore whitespace discrepancies)
     (my $a_trimmed = $actual) =~ s/\s+/ /g;
 
@@ -309,4 +282,72 @@ sub handle_handle {
     return;
 }
 
+
+####################
+#  operation_name  #  Given a method + endpoint, return the swagger operation
+####################
+sub operation_name {
+    my ($method, $endpoint) = @_;
+
+    # /libpod/foo/bar -> (libpod, foo, bar)
+    my @endpoints = grep { /\S/ } split '/', $endpoint;
+
+    # /libpod endpoints -> add 'Libpod' to end, e.g. PodStatsLibpod
+    my $Libpod = '';
+    my $main = shift(@endpoints);
+    if ($main eq 'libpod') {
+        $Libpod = ucfirst($main);
+        $main = shift(@endpoints);
+    }
+    $main =~ s/s$//;         # e.g. Volumes -> Volume
+
+    # Next path component is an optional action:
+    #    GET    /containers/json               -> ContainerList
+    #    DELETE /libpod/containers/{name}      -> ContainerDelete
+    #    GET    /libpod/containers/{name}/logs -> ContainerLogsLibpod
+    my $action = shift(@endpoints) || 'list';
+    $action = 'list'   if $action eq 'json';
+    $action = 'delete' if $method eq 'DELETE';
+
+    # Anything with {id}, {name}, {name:..} may have a following component
+    if ($action =~ m!\{.*\}!) {
+        $action = shift(@endpoints) || 'inspect';
+        $action = 'inspect' if $action eq 'json';
+    }
+
+    # All sorts of special cases
+    if ($action eq 'df') {
+        $action = 'dataUsage';
+    }
+    # Grrrrrr, this one is annoying: some operations get an extra 'All'
+    elsif ($action =~ /^(delete|get|stats)$/ && $endpoint !~ /\{/) {
+        $action .= "All";
+        $main .= 's' if $main eq 'container';
+    }
+    # No real way to used MixedCase in an endpoint, so we have to hack it here
+    elsif ($action eq 'showmounted') {
+        $action = 'showMounted';
+    }
+    # Ping is a special endpoint, and even if /libpod/_ping, no 'Libpod'
+    elsif ($main eq '_ping') {
+        $main = 'system';
+        $action = 'ping';
+        $Libpod = '';
+    }
+    # Top-level compat endpoints
+    elsif ($main =~ /^(build|commit)$/) {
+        $main   = 'image';
+        $action = $1;
+    }
+    # Top-level system endpoints
+    elsif ($main =~ /^(auth|event|info|version)$/) {
+        $main   = 'system';
+        $action = $1;
+        $action .= 's' if $action eq 'event';
+    }
+
+    return "\u${main}\u${action}$Libpod";
+}
+
+
 1;
-- 
cgit v1.2.3-54-g00ecf