more

index.d.ts

@@ -1,4 +1,5 @@
-type ResourceRequirements = import("kubernetes-models/v1").IResourceRequirements;
+type ResourceRequirements =
+  import("kubernetes-models/v1").IResourceRequirements;
 type Namespace = import("kubernetes-models/v1").INamespace;
 type Deployment = import("kubernetes-models/apps/v1").IDeployment;
 type StatefulSet = import("kubernetes-models/apps/v1").IStatefulSet;
@@ -10,17 +11,18 @@ type CronJob = import("kubernetes-models/batch/v1").ICronJob;
 type ConfigMap = import("kubernetes-models/v1").IConfigMap;
 type Secret = import("kubernetes-models/v1").ISecret;
 
-type Utils = import("./packages/common/utils").default;
-
-type UtilsType = Utils;
+type Utils = import("./packages/common/utils").Utils;
 
+// todo: use officiel model
 interface KappConfig {
   kind: "Config";
   apiVersion: string;
   metadata: Record<string, any>;
   spec?: Record<string, any>;
 }
 
+// todo: add sealed-secret model
+
 declare namespace Kontinuous {
   // the Type `Manifest` doesnt exit in kubernetes-models. we define every kind of model we need.
   type Manifest =
@@ -90,13 +92,13 @@ declare namespace Kontinuous {
     glue?: string;
   };
 
-  type Utils = import("./packages/common/utils").default;
-
   type PatchContext = {
     utils: Utils;
     //@ts-ignore
     logger;
     //@ts-ignore
+    kubectl;
+    //@ts-ignore
     needBin?;
     // todo: extract from value-compilers
     values: {

package.json

@@ -15,6 +15,7 @@
     "@types/lodash.omit": "^4.5.7",
     "@types/lodash.pick": "^4.4.7",
     "@types/lodash.set": "^4.3.7",
+    "@types/micromatch": "^4.0.2",
     "@types/node": "^18.11.18",
     "docsify-cli": "^4.4.4",
     "eslint": "^8.31.0",

packages/common/utils/async-shell.js

@@ -50,7 +50,7 @@ const promiseFromChildProcess = (child, callback, logger, extraOptions) => {
 }
 /**
  *
- * @param {string} arg
+ * @param {string|string[]} arg
  * @param {Record<string, any>} options
  * @param {null | ((child: import("child_process").ChildProcessWithoutNullStreams) => void)} callback
  * @param {Kontinuous.PatchContext["logger"]} logger

packages/common/utils/index.d.ts

@@ -1,32 +1,41 @@
+// import JSDoc definitions
 type Slug = typeof import("./slug");
 type KindIsRunnable = typeof import("./kind-is-runnable");
 type AsyncShell = typeof import("./async-shell");
 type IsVersionTag = typeof import("./is-version-tag");
+type SanitizeLabel = typeof import("./sanitize-label");
+type IgnoreYarnState = typeof import("./ignore-yarn-state");
+type PatternMatch = typeof import("./pattern-match");
+type KubectlRetry = typeof import("./kubectl-retry");
 
-// TODO : fetch from source JSDoc
+// TODO : fetch from ./*.js
+// for some reason the description from source JSDoc isnt displayed
 interface Utils {
   /** execute some async shell command */
   asyncShell: AsyncShell;
   /** Return slugified, hostname-friendly string */
   slug: Slug;
   /** Check if some branch is valid semantic-release tag: vx.y.z */
   isVersionTag: IsVersionTag;
-  sanitizeLabel: (label: string) => string;
+  /** exclude non-alphanums chars */
+  sanitizeLabel: SanitizeLabel;
   //@ts-ignore
   yaml;
   //@ts-ignore
   logger;
   //@ts-ignore
   KontinuousPluginError;
   //@ts-ignore
-  patternMatch;
-  // typeguard . todo: extract from utils/kind-is-runnable
+  patternMatch: PatternMatch;
+  // check if the manifest is "runnable" in kubernetes
+  // act as a typeguard
   kindIsRunnable: KindIsRunnable;
-  //@ts-ignore
-  kubectlRetry;
+  /** Run kubectl with exponential backoff */
+  kubectlRetry: KubectlRetry;
   //@ts-ignore
   needKubectl;
-  ignoreYarnState: (src: string) => boolean;
+  /** check if some path should be ignored */
+  ignoreYarnState: IgnoreYarnState;
 }
 
-export default Utils;
+export { Utils };

packages/common/utils/kubectl-retry.js

@@ -7,6 +7,21 @@ const defaultLogger = require("./logger")
 const retriableOnBrokenCluster = require("./retriable-on-broken-cluster")
 const retriableNetwork = require("./retriable-network")
 
+/**
+ * @typedef {Object} KubectlRunOptions
+ * @prop {string} [kubeconfig]
+ * @prop {string} [kubeconfigContext]
+ * @prop {string[]} [ignoreErrors]
+ * @prop {string} [stdin]
+ * @prop {import('child_process').ChildProcess[]} [collectProcesses]
+ */
+
+/**
+ *
+ * @param {string[]} kubectlArgs
+ * @param {KubectlRunOptions} options
+ * @returns void
+ */
 const kubectlRun = async (kubectlArgs, options = {}) => {
   const {
     kubeconfig,
@@ -77,6 +92,23 @@ const kubectlRun = async (kubectlArgs, options = {}) => {
   })
 }
 
+/**
+ * @typedef {Object} KubectlRetryOptions
+ * @prop {any} [logger]
+ * @prop {any} [sentry]
+ * @prop {Record<string, any>} [retryOptions]
+ * @prop {boolean} [logError]
+ * @prop {boolean} [logInfo]
+ * @prop {import('child_process').ChildProcess[]} [collectProcesses]
+ * @prop {boolean} [surviveOnBrokenCluster]
+ */
+
+/**
+ *
+ * @param {string[]} kubectlArgs
+ * @param {KubectlRetryOptions} options
+ * @returns string
+ */
 module.exports = async (kubectlArgs, options = {}) => {
   const {
     logger = defaultLogger,

packages/common/utils/pattern-match.js

@@ -1,5 +1,11 @@
 const micromatch = require("micromatch")
 
+/**
+ * @param {string[]} str
+ * @param {string} pattern
+ * @param {Record<string, any>} options
+ * @returns
+ */
 module.exports = (str, pattern, options = {}) =>
   micromatch.match(str, pattern, {
     regex: true,

packages/common/utils/sanitize-label.js

@@ -1,3 +1,8 @@
+/**
+ * @param {string} label
+ * @param {string} prefixIfNeeded
+ * @returns string
+ */
 module.exports = (label, prefixIfNeeded = "v") => {
   label = label.replace(/[^a-zA-Z0-9._-]+/g, "-")
   if (!/^[a-zA-Z0-9]/.test(label)) {

yarn.lock

@@ -2722,6 +2722,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@types/braces@npm:*":
+  version: 3.0.1
+  resolution: "@types/braces@npm:3.0.1"
+  checksum: c0d610f2474b174dc87946b57a8a7ecf5a14a49ef4217fc1134bcd32bcbd8a07eeaee5ea88b861effeee554cf28dc62867008e39049a574a2162985a40586333
+  languageName: node
+  linkType: hard
+
 "@types/cacheable-request@npm:^6.0.1":
   version: 6.0.2
   resolution: "@types/cacheable-request@npm:6.0.2"
@@ -2930,6 +2937,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@types/micromatch@npm:^4.0.2":
+  version: 4.0.2
+  resolution: "@types/micromatch@npm:4.0.2"
+  dependencies:
+    "@types/braces": "npm:*"
+  checksum: ac7ec28d57ac61a85bd2859c69d096192e8ef66cc9d3c5fcb4531eeec3b090b1ff1be132e65eff6a16be14b9a30083cf488a402c094890c654db861aafee4669
+  languageName: node
+  linkType: hard
+
 "@types/mime@npm:^1":
   version: 1.3.2
   resolution: "@types/mime@npm:1.3.2"
@@ -13911,6 +13927,7 @@ __metadata:
     "@types/lodash.omit": "npm:^4.5.7"
     "@types/lodash.pick": "npm:^4.4.7"
     "@types/lodash.set": "npm:^4.3.7"
+    "@types/micromatch": "npm:^4.0.2"
     "@types/node": "npm:^18.11.18"
     docsify-cli: "npm:^4.4.4"
     eslint: "npm:^8.31.0"