Minor API docs improvement (#90)

* Minor change to api docs
* Throw ConfigError instead of TypeError in Configs methods
* Temp hack with --global-scope

Author: frankfarzan

docs/api/classes/_types_.configs.md

@@ -40,7 +40,7 @@ Creates a Config.
 
 Name | Type | Default | Description |
 ------ | ------ | ------ | ------ |
-`input` | [KubernetesObject](../interfaces/_types_.kubernetesobject.md)[] | [] | Input Kubernetes objects. If supplied multiple objects with the same (Group, Kind, Namespace, Name) discards all but the last one. Does not preserve insertion order of the passed objects. |
+`input` | [KubernetesObject](../interfaces/_types_.kubernetesobject.md)[] | [] | Input Kubernetes objects. If supplied multiple objects with the same [kubernetesKey](../modules/_types_.md#kuberneteskey) discards all but the last one. Does not preserve insertion order of the given objects. |
 `functionConfig?` | [KubernetesObject](../interfaces/_types_.kubernetesobject.md) | - | Kubernetes object used to parameterize the function's behavior.  |
 
 **Returns:** *[Configs](_types_.configs.md)*
@@ -51,9 +51,9 @@ Name | Type | Default | Description |
 
 ▸ **delete**(...`objects`: [KubernetesObject](../interfaces/_types_.kubernetesobject.md)[]): *void*
 
-Deletes all objects with the same (Group, Kind, Namespace, Name) as any of the passed objects.
+Deletes all objects with the same [kubernetesKey](../modules/_types_.md#kuberneteskey) as any of the given objects.
 
-Does not throw if passed duplicates or keys which are not present in the Configs.
+Does not throw if given duplicates or keys which are not present in the Configs.
 
 **Parameters:**
 
@@ -79,7 +79,7 @@ ___
 
 ▸ **get**<**Kind**>(`isKind`: function): *Kind[]*
 
-Returns an array of objects matching the passed Kind type predicate.
+Returns an array of objects matching the given Kind type predicate.
 
 Casts to an array of Kind. May throw if isKind is incorrect.
 
@@ -139,12 +139,12 @@ ___
 
 Returns the value for the given key if functionConfig is of kind ConfigMap.
 
-Throws a TypeError exception if functionConfig kind is not a ConfigMap.
+Throws a ConfigError if functionConfig kind is not a ConfigMap.
 
 Returns undefined if functionConfig is undefined OR
 if the ConfigMap has no such key in the 'data' section.
 
-**`key`** key The key in the 'data' field in the ConfigMap object passed as the functionConfig.
+**`key`** key The key in the 'data' field in the ConfigMap object given as the functionConfig.
 
 **Parameters:**
 
@@ -160,7 +160,7 @@ ___
 
 ▸ **getFunctionConfigValueOrThrow**(`key`: string): *string*
 
-Similar to [getFunctionConfigValue](_types_.configs.md#getfunctionconfigvalue) except it throws a TypeError exception if the given key is undefined.
+Similar to [getFunctionConfigValue](_types_.configs.md#getfunctionconfigvalue) except it throws a ConfigError if the given key is undefined.
 
 **Parameters:**
 
@@ -210,12 +210,12 @@ ___
 
 Inserts objects into the Configs.
 
-If another object already in Configs has the same (Group, Kind, Namespace, Name), replaces that one with the
-passed object.
+If another object already in Configs has the same [kubernetesKey](../modules/_types_.md#kuberneteskey), replaces that one with the
+given object.
 
-If multiple objects have the same (Group, Kind, Namespace, Name), discards all but the last one.
+If inserting multiple objects with the same [kubernetesKey](../modules/_types_.md#kuberneteskey), discards all but the last one.
 
-Does not preserve insertion order of the passed objects.
+Does not preserve insertion order of the given objects.
 
 **Parameters:**
 

docs/api/modules/_types_.md

@@ -16,7 +16,7 @@
 ### Functions
 
 * [isKubernetesObject](_types_.md#iskubernetesobject)
-* [kubernetesKeyFn](_types_.md#kuberneteskeyfn)
+* [kubernetesKey](_types_.md#kuberneteskey)
 
 ## Functions
 
@@ -36,11 +36,11 @@ Name | Type |
 
 ___
 
-###  kubernetesKeyFn
+###  kubernetesKey
 
-▸ **kubernetesKeyFn**(`o`: [KubernetesObject](../interfaces/_types_.kubernetesobject.md)): *string*
+▸ **kubernetesKey**(`o`: [KubernetesObject](../interfaces/_types_.kubernetesobject.md)): *string*
 
-Generates the primary key for a Kubernetes objects in Configs.
+A unique key for a Kubernetes object defined as tuple of (apiVersion, kind, namespace, name).
 
 **Parameters:**
 

docs/run.md

@@ -75,7 +75,7 @@ EOF
 You should see the same results as in the previous examples:
 
 ```sh
-kpt fn run .
+kpt fn run --global-scope .
 git status
 ```
 
@@ -100,7 +100,7 @@ EOF
 `fn run` executes both functions:
 
 ```sh
-kpt fn run .
+kpt fn run --global-scope .
 ```
 
 In this case, `validate-rolebinding` will find policy violations and fail with a non-zero exit code.

ts/demo-functions/package.json

@@ -9,7 +9,7 @@
     "build": "tsc",
     "watch": "tsc --watch",
     "clean": "rm -Rf node_modules/ dist/",
-    "lint": "tslint -p package.json; prettier \"src/**\" \"*.json\" --check",
+    "lint": "tslint -p package.json && prettier \"src/**\" \"*.json\" --check",
     "lint-license": "license-checker --onlyAllow 'Apache-2.0;MIT;BSD;BSD-2-Clause;BSD-3-Clause;ISC;CC-BY-3.0;CC0-1.0;Unlicense'",
     "format": "prettier \"src/**\" \"*.json\" --write",
     "pretest": "npm run build",

ts/demo-functions/src/expand_team_test.ts

@@ -20,17 +20,6 @@ import { Namespace } from './gen/io.k8s.api.core.v1';
 import { ClusterRole, RoleBinding, Subject } from './gen/io.k8s.api.rbac.v1';
 import { expandTeamCr } from './expand_team_cr';
 
-function team(name: string, ...roles: Team.Spec.Item[]): Team {
-  const team = new Team({
-    metadata: { name },
-    spec: {},
-  });
-  if (roles.length) {
-    team.spec.roles = roles;
-  }
-  return team;
-}
-
 const RUNNER = new TestRunner(expandTeamCr);
 
 describe(expandTeamCr.name, () => {
@@ -225,3 +214,14 @@ describe(expandTeamCr.name, () => {
     ),
   );
 });
+
+function team(name: string, ...roles: Team.Spec.Item[]): Team {
+  const team = new Team({
+    metadata: { name },
+    spec: {},
+  });
+  if (roles.length) {
+    team.spec.roles = roles;
+  }
+  return team;
+}

ts/demo-functions/src/label_namespace.ts

@@ -17,8 +17,8 @@
 import { addLabel, Configs } from '@googlecontainertools/kpt-functions';
 import { isNamespace } from './gen/io.k8s.api.core.v1';
 
-export const LABEL_NAME = 'label_name';
-export const LABEL_VALUE = 'label_value';
+const LABEL_NAME = 'label_name';
+const LABEL_VALUE = 'label_value';
 
 export async function labelNamespace(configs: Configs) {
   const labelName = configs.getFunctionConfigValueOrThrow(LABEL_NAME);

ts/demo-functions/src/label_namespace_test.ts

@@ -15,31 +15,29 @@
  */
 
 import { Configs, TestRunner } from '@googlecontainertools/kpt-functions';
-import { labelNamespace, LABEL_NAME, LABEL_VALUE } from './label_namespace';
+import { labelNamespace } from './label_namespace';
 import { Namespace, ConfigMap } from './gen/io.k8s.api.core.v1';
 
+const RUNNER = new TestRunner(labelNamespace);
 const TEST_NAMESPACE = 'testNamespace';
 const TEST_LABEL_NAME = 'costCenter';
 const TEST_LABEL_VALUE = 'xyz';
+const FUNC_CONFIG: ConfigMap = new ConfigMap({
+  metadata: { name: 'config' },
+  data: { label_name: 'costCenter', label_value: 'xyz' },
+});
 
 describe('labelNamespace', () => {
-  let functionConfig = ConfigMap.named('foo');
-  functionConfig.data = {};
-  functionConfig.data[LABEL_NAME] = TEST_LABEL_NAME;
-  functionConfig.data[LABEL_VALUE] = TEST_LABEL_VALUE;
-
-  const RUNNER = new TestRunner(labelNamespace);
-
-  it('empty input ok', RUNNER.assertCallback(new Configs(undefined, functionConfig)));
+  it('empty input ok', RUNNER.assertCallback(new Configs(undefined, FUNC_CONFIG)));
 
   it('requires functionConfig', RUNNER.assertCallback(undefined, undefined, TypeError));
 
   it('adds label namespace when metadata.labels is undefined', async () => {
-    const actual = new Configs(undefined, functionConfig);
-    actual.insert(Namespace.named(TEST_NAMESPACE));
+    const input = new Configs(undefined, FUNC_CONFIG);
+    input.insert(Namespace.named(TEST_NAMESPACE));
 
-    const expected = new Configs();
-    expected.insert(
+    const output = new Configs();
+    output.insert(
       new Namespace({
         metadata: {
           name: TEST_NAMESPACE,
@@ -48,12 +46,12 @@ describe('labelNamespace', () => {
       }),
     );
 
-    await RUNNER.assert(actual, expected);
+    await RUNNER.assert(input, output);
   });
 
   it('adds label to namespace when metadata.labels is defined', async () => {
-    const actual = new Configs(undefined, functionConfig);
-    actual.insert(
+    const input = new Configs(undefined, FUNC_CONFIG);
+    input.insert(
       new Namespace({
         metadata: {
           name: TEST_NAMESPACE,
@@ -62,8 +60,8 @@ describe('labelNamespace', () => {
       }),
     );
 
-    const expected = new Configs();
-    expected.insert(
+    const output = new Configs();
+    output.insert(
       new Namespace({
         metadata: {
           name: TEST_NAMESPACE,
@@ -75,6 +73,6 @@ describe('labelNamespace', () => {
       }),
     );
 
-    await RUNNER.assert(actual, expected);
+    await RUNNER.assert(input, output);
   });
 });

ts/demo-functions/src/mutate_psp_test.ts

@@ -18,25 +18,10 @@ import { Configs, TestRunner } from '@googlecontainertools/kpt-functions';
 import { PodSecurityPolicy } from './gen/io.k8s.api.policy.v1beta1';
 import { mutatePsp } from './mutate_psp';
 
-function psp(allowPrivilegeEscalation: boolean): PodSecurityPolicy {
-  return new PodSecurityPolicy({
-    metadata: {
-      name: 'pod',
-    },
-    spec: {
-      allowPrivilegeEscalation,
-      fsGroup: { rule: 'RunAsAny' },
-      runAsUser: { rule: 'RunAsAny' },
-      seLinux: { rule: 'RunAsAny' },
-      supplementalGroups: { rule: 'RunAsAny' },
-    },
-  });
-}
-
 const RUNNER = new TestRunner(mutatePsp);
 
 describe('mutatePsp', () => {
-  it('passes empty repos', RUNNER.assertCallback());
+  it('empty configs is noop', RUNNER.assertCallback());
 
   it(
     'modifies PSP with allowPrivilegeEscalation = true to false',
@@ -48,3 +33,18 @@ describe('mutatePsp', () => {
     RUNNER.assertCallback(new Configs([psp(false)])),
   );
 });
+
+function psp(allowPrivilegeEscalation: boolean): PodSecurityPolicy {
+  return new PodSecurityPolicy({
+    metadata: {
+      name: 'pod',
+    },
+    spec: {
+      allowPrivilegeEscalation,
+      fsGroup: { rule: 'RunAsAny' },
+      runAsUser: { rule: 'RunAsAny' },
+      seLinux: { rule: 'RunAsAny' },
+      supplementalGroups: { rule: 'RunAsAny' },
+    },
+  });
+}

ts/demo-functions/src/read_yaml.ts

@@ -17,13 +17,22 @@
 import * as fs from 'fs';
 import * as glob from 'glob';
 import { safeLoadAll } from 'js-yaml';
-import * as kpt from '@googlecontainertools/kpt-functions';
 import * as path from 'path';
+import {
+  Configs,
+  ConfigError,
+  MultiConfigError,
+  isKubernetesObject,
+  ConfigFileError,
+  addAnnotation,
+  SOURCE_PATH_ANNOTATION,
+  SOURCE_INDEX_ANNOTATION,
+} from '@googlecontainertools/kpt-functions';
 
 export const SOURCE_DIR = 'source_dir';
 export const FILTER_IVNALID = 'filter_invalid';
 
-export async function readYaml(configs: kpt.Configs) {
+export async function readYaml(configs: Configs) {
   // Get the parameters.
   const sourceDir = configs.getFunctionConfigValueOrThrow(SOURCE_DIR);
   const ignoreInvalid = configs.getFunctionConfigValue(FILTER_IVNALID) === 'true';
@@ -35,13 +44,13 @@ export async function readYaml(configs: kpt.Configs) {
   const files = glob.sync(sourceDir + '/**/*.+(yaml|yml)');
 
   // Parse each file and convert it to a KubernetesObject.
-  const errors: kpt.ConfigError[] = files
+  const errors: ConfigError[] = files
     .map((f) => parseFile(configs, sourceDir, f, ignoreInvalid))
     .filter((err) => err !== undefined)
-    .map((err) => err as kpt.ConfigError);
+    .map((err) => err as ConfigError);
 
   if (errors.length) {
-    throw new kpt.MultiConfigError(
+    throw new MultiConfigError(
       `Found files containing invalid objects. To filter invalid objects set ${FILTER_IVNALID} to 'true'.`,
       errors,
     );
@@ -67,21 +76,21 @@ metadata:
 `;
 
 function parseFile(
-  configs: kpt.Configs,
+  configs: Configs,
   sourceDir: string,
   file: string,
   ignoreInvalid: boolean,
-): kpt.ConfigError | undefined {
+): ConfigError | undefined {
   const contents = readFileOrThrow(file);
   let objects = safeLoadAll(contents);
 
   // Filter for objects that are not KubernetesObject. This is conditional on 'ignoreValid' parameter.
-  const invalidObjects: object[] = objects.filter((o) => !kpt.isKubernetesObject(o));
+  const invalidObjects: object[] = objects.filter((o) => !isKubernetesObject(o));
   if (invalidObjects.length) {
     if (ignoreInvalid) {
-      objects = objects.filter((o) => kpt.isKubernetesObject(o));
+      objects = objects.filter((o) => isKubernetesObject(o));
     } else {
-      return new kpt.ConfigFileError(
+      return new ConfigFileError(
         `File contains invalid Kubernetes objects '${JSON.stringify(invalidObjects)}'`,
         file,
       );
@@ -91,8 +100,8 @@ function parseFile(
   // Add the standard path and index annotations to preserve the filesystem hierarchy
   // and ordering within a file.
   objects.forEach((o, i) => {
-    kpt.addAnnotation(o, kpt.SOURCE_PATH_ANNOTATION, path.relative(sourceDir, file));
-    kpt.addAnnotation(o, kpt.SOURCE_INDEX_ANNOTATION, i.toString());
+    addAnnotation(o, SOURCE_PATH_ANNOTATION, path.relative(sourceDir, file));
+    addAnnotation(o, SOURCE_INDEX_ANNOTATION, i.toString());
   });
 
   configs.insert(...objects);