Codify some hsettp heurisitcs that Greg added (#614)

Greg changed the exact match search for an operation to a best match at some point. I think the idea is pretty solid, but a casual user would never know about it. A casual user is anyone but Greg for the record :). Another thing that Greg added was hiding certain operations from the general help output because their names were too long. For instance, getting perf counter events in a certain set in a certain file on a certain line. What a mouthful! So I went ahead and hid obvious candidates instead of relying on the length heuristic that Greg originally went by. Signed-off-by: Tristan Partin <[email protected]>
hse-project · Feb 16, 2023 · 1fbb107 · 1fbb107
1 parent f66020b
commit 1fbb107
Show file tree

Hide file tree

Showing 4 changed files with 190 additions and 97 deletions.
diff --git a/.spectral.yaml b/.spectral.yaml
@@ -42,6 +42,27 @@ rules:
     then:
       field: x-options
       function: truthy
+  x-alias-schema:
+    description: x-alias must have the correct schema.
+    message: "{{description}} {{error}}"
+    given: "$.paths[*][get,put,post,delete,options,head,patch,trace].x-alias"
+    severity: error
+    then:
+      function: schema
+      functionOptions:
+        schema:
+          type: string
+          pattern: "^[a-z][a-z-]*[a-z]$"
+  x-hide-schema:
+    description: x-hide must have the correct schema.
+    message: "{{description}} {{error}}"
+    given: "$.paths[*][get,put,post,delete,options,head,patch,trace].x-hide"
+    severity: error
+    then:
+      function: schema
+      functionOptions:
+        schema:
+          type: boolean
   x-options-schema:
     description: x-options must have the correct schema.
     message: "{{description}} {{error}}"

diff --git a/docs/openapi.json b/docs/openapi.json
@@ -23,6 +23,7 @@
       "get": {
         "description": "Get all event counter information.",
         "operationId": "events-get",
+        "x-alias": "events",
         "x-options": [
           {
             "$ref": "#/components/x-options/format"
@@ -95,6 +96,7 @@
       "get": {
         "description": "Get all event counter information for file.",
         "operationId": "events-in-file-get",
+        "x-hide": true,
         "x-options": [
           {
             "$ref": "#/components/x-options/format"
@@ -170,6 +172,7 @@
       "get": {
         "description": "Get all event counter information for function in file.",
         "operationId": "events-in-file-in-function-get",
+        "x-hide": true,
         "x-options": [
           {
             "$ref": "#/components/x-options/format"
@@ -248,6 +251,7 @@
       "get": {
         "description": "Get all event counter information for function on line number of file.",
         "operationId": "events-in-file-in-function-on-lineno-get",
+        "x-hide": true,
         "x-options": [
           {
             "$ref": "#/components/x-options/format"
@@ -315,6 +319,7 @@
       "get": {
         "description": "Get virtual memory statistics.",
         "operationId": "kmc-vmstat-get",
+        "x-alias": "vmstat",
         "x-options": [
           {
             "$ref": "#/components/x-options/format"
@@ -642,6 +647,7 @@
       "get": {
         "description": "Get all performance counter information.",
         "operationId": "perfc-get",
+        "x-alias": "perfc",
         "x-options": [
           {
             "$ref": "#/components/x-options/format"
@@ -691,6 +697,7 @@
       "get": {
         "description": "Get all performance counter information for group.",
         "operationId": "perfc-in-group-get",
+        "x-hide": true,
         "x-options": [
           {
             "$ref": "#/components/x-options/format"
@@ -743,6 +750,7 @@
       "get": {
         "description": "Get all performance counter information for group in set.",
         "operationId": "perfc-in-group-in-set-get",
+        "x-hide": true,
         "x-options": [
           {
             "$ref": "#/components/x-options/format"
@@ -798,6 +806,7 @@
       "get": {
         "description": "Get all performance counter information for group in set with name.",
         "operationId": "perfc-in-group-in-set-with-name-get",
+        "x-hide": true,
         "x-options": [
           {
             "$ref": "#/components/x-options/format"
@@ -842,6 +851,7 @@
       "get": {
         "description": "Get the process' `/proc/self/task/[tid]/stat` information.",
         "operationId": "workqueues-get",
+        "x-alias": "ps",
         "x-options": [
           {
             "$ref": "#/components/x-options/format"
@@ -1181,6 +1191,7 @@
       "get": {
         "description": "Get information about all current KVDB compaction jobs.",
         "operationId": "kvdb-csched-get",
+        "x-alias": "csched",
         "x-options": [
           {
             "$ref": "#/components/x-options/format"
@@ -1433,6 +1444,7 @@
       "get": {
         "description": "Get KVDB home.",
         "operationId": "kvdb-home-get",
+        "x-alias": "home",
         "x-options": [
           {
             "$ref": "#/components/x-options/format"
@@ -1745,6 +1757,7 @@
       "get": {
         "description": "Get all KVS names.",
         "operationId": "kvdb-kvs-get",
+        "x-alias": "kvs",
         "x-options": [
           {
             "$ref": "#/components/x-options/format"
@@ -1860,6 +1873,7 @@
       "get": {
         "description": "Get all performance counter information.",
         "operationId": "kvdb-perfc-in-set-get",
+        "x-hide": true,
         "x-options": [
           {
             "$ref": "#/components/x-options/format"
@@ -1915,6 +1929,7 @@
       "get": {
         "description": "Get all performance counter information.",
         "operationId": "kvdb-perfc-in-set-with-name-get",
+        "x-hide": true,
         "x-options": [
           {
             "$ref": "#/components/x-options/format"
@@ -1967,6 +1982,7 @@
       "get": {
         "description": "Get information about the KVS's cN tree.",
         "operationId": "kvs-cn-tree-get",
+        "x-alias": "tree",
         "x-options": [
           {
             "$ref": "#/components/x-options/format"
@@ -2335,6 +2351,7 @@
       "get": {
         "description": "Get all performance counter information.",
         "operationId": "kvs-perfc-in-set-get",
+        "x-hide": true,
         "x-options": [
           {
             "$ref": "#/components/x-options/format"
@@ -2393,6 +2410,7 @@
       "get": {
         "description": "Get all performance counter information.",
         "operationId": "kvs-perfc-in-set-with-name-get",
+        "x-hide": true,
         "x-options": [
           {
             "$ref": "#/components/x-options/format"

diff --git a/tools/hsettp/README.md b/tools/hsettp/README.md
@@ -20,6 +20,25 @@ description is marked up with extension fields in order to create a useful tool.
 
 ### Specification Extensions
 
+#### `x-alias`
+
+A few of the operations are commonly used, so providing an alias with a more
+memorable value can be convenient.
+
+##### Schmea
+
+String matching `^[a-z]+[a-z-]?[a-z]+$`.
+
+#### `x-hide`
+
+Some of our operations are not particularly useful unless you really need that
+information. If set to `true`, the operation will be hidden from the root help
+output unless verbosity is enabled.
+
+##### Schema
+
+Boolean
+
 #### `x-options`
 
 Used to add options to a particular operation. This can include `help`,