Merge pull request #42 from alma-cdk/beta-add-warnings

chore: add warnings about use of to-be-deprecated feature flags

.projenrc.ts

@@ -134,9 +134,11 @@ new TextFile(project, "sonar-project.properties", {
     "sonar.sources=./src",
     "sonar.tests=./test",
     "sonar.test.inclusions=**/*.test.*",
-    "sonar.issue.ignore.multicriteria=e1",
+    "sonar.issue.ignore.multicriteria=e1,e2",
     "sonar.issue.ignore.multicriteria.e1.ruleKey=typescript:S1874",
     "sonar.issue.ignore.multicriteria.e1.resourceKey=src/smartstack/tags/*.ts",
+    "sonar.issue.ignore.multicriteria.e2.ruleKey=typescript:S1874",
+    "sonar.issue.ignore.multicriteria.e2.resourceKey=src/project/deprecation-warnings.ts",
   ],
 });
 

src/feature-flags/index.ts

@@ -0,0 +1,2 @@
+export * from "./legacyTags";
+export * from "./v0Tags";

src/feature-flags/legacyTags.test.ts

@@ -0,0 +1,22 @@
+import { useLegacyTags, LEGACY_TAGS_CONTEXT_KEY } from "./legacyTags";
+import { TestableResource } from "../__test__/TestableResource";
+
+describe("useLegacyTags", () => {
+  test("context key is correct", () => {
+    expect(LEGACY_TAGS_CONTEXT_KEY).toBe("@alma-cdk/project:legacyTags");
+  });
+
+  test("returns false if the context key is not set", () => {
+    const scope = new TestableResource();
+    expect(useLegacyTags(scope)).toBe(false);
+  });
+
+  test("returns true if the context key is set", () => {
+    const scope = new TestableResource({
+      context: {
+        "@alma-cdk/project:legacyTags": true,
+      },
+    });
+    expect(useLegacyTags(scope)).toBe(true);
+  });
+});

src/feature-flags/legacyTags.ts

@@ -0,0 +1,13 @@
+import { Construct } from "constructs";
+
+export const LEGACY_TAGS_CONTEXT_KEY = "@alma-cdk/project:legacyTags";
+
+/**
+ * Enforces usage of https://github.com/almamedia/alma-cdk-jsii-tag-and-name
+ * (for AWS CDK v1) compatible tagging behavior.
+ *
+ * @deprecated This behavior is not encouraged and will be removed in v2. Additionally according to GitHub search, this is not used anymore.
+ */
+export function useLegacyTags(scope: Construct): boolean {
+  return scope.node.tryGetContext(LEGACY_TAGS_CONTEXT_KEY) === true;
+}

src/feature-flags/v0Tags.test.ts

@@ -0,0 +1,22 @@
+import { useCompatibilityV0Tags, V0_TAGS_CONTEXT_KEY } from "./v0Tags";
+import { TestableResource } from "../__test__/TestableResource";
+
+describe("useCompatibilityV0Tags", () => {
+  test("context key is correct", () => {
+    expect(V0_TAGS_CONTEXT_KEY).toBe("@alma-cdk/project:compatibility:v0:tags");
+  });
+
+  test("returns false if the context key is not set", () => {
+    const scope = new TestableResource();
+    expect(useCompatibilityV0Tags(scope)).toBe(false);
+  });
+
+  test("returns true if the context key is set", () => {
+    const scope = new TestableResource({
+      context: {
+        "@alma-cdk/project:compatibility:v0:tags": true,
+      },
+    });
+    expect(useCompatibilityV0Tags(scope)).toBe(true);
+  });
+});

src/feature-flags/v0Tags.ts

@@ -0,0 +1,15 @@
+import { Construct } from "constructs";
+
+export const V0_TAGS_CONTEXT_KEY = "@alma-cdk/project:compatibility:v0:tags";
+
+/**
+ * Compatibility flag for v0 tagging behavior.
+ * Due to a bug in v0, the `Contact` and `Organization` tags were NOT applied as they should have.
+ * This flag can be used to enforce behavior that matches v0 implementation:
+ * I.e. `Contact` and `Organization` tags are NOT applied.
+ *
+ * @deprecated This behavior is not encouraged and will be removed in v2.
+ */
+export function useCompatibilityV0Tags(scope: Construct): boolean {
+  return scope.node.tryGetContext(V0_TAGS_CONTEXT_KEY) === true;
+}

src/project/deprecation-warnings.test.ts

@@ -0,0 +1,53 @@
+import { warnAboutDeprecatedTags } from "./deprecation-warnings";
+import { expectErrorMetadata } from "../__test__/expectErrorMetadata";
+import { TestableResource } from "../__test__/TestableResource";
+
+describe("@alma-cdk/project:legacyTags", () => {
+  test("feature flag present", () => {
+    const testable = new TestableResource({
+      context: {
+        "@alma-cdk/project:legacyTags": true,
+      },
+    });
+
+    warnAboutDeprecatedTags(testable);
+
+    expectErrorMetadata(
+      testable,
+      expect.stringContaining("@alma-cdk/project@v1:legacy-tags"),
+    );
+  });
+
+  test("feature flag missing", () => {
+    const testable = new TestableResource();
+
+    warnAboutDeprecatedTags(testable);
+
+    expectErrorMetadata(testable, undefined);
+  });
+});
+
+describe("@alma-cdk/project:compatibility:v0:tags", () => {
+  test("feature flag present", () => {
+    const testable = new TestableResource({
+      context: {
+        "@alma-cdk/project:compatibility:v0:tags": true,
+      },
+    });
+
+    warnAboutDeprecatedTags(testable);
+
+    expectErrorMetadata(
+      testable,
+      expect.stringContaining("@alma-cdk/project@v1:compatibility-v0-tags"),
+    );
+  });
+
+  test("feature flag missing", () => {
+    const testable = new TestableResource();
+
+    warnAboutDeprecatedTags(testable);
+
+    expectErrorMetadata(testable, undefined);
+  });
+});

src/project/deprecation-warnings.ts

@@ -0,0 +1,24 @@
+import { Annotations } from "aws-cdk-lib";
+import { Construct } from "constructs";
+import {
+  useLegacyTags,
+  useCompatibilityV0Tags,
+  LEGACY_TAGS_CONTEXT_KEY,
+  V0_TAGS_CONTEXT_KEY,
+} from "../feature-flags";
+
+export function warnAboutDeprecatedTags(scope: Construct) {
+  if (useLegacyTags(scope)) {
+    Annotations.of(scope).addWarningV2(
+      "@alma-cdk/project@v1:legacy-tags",
+      `Using @almamedia-cdk/tag-and-name (for AWS CDK v1) construct's legacy tagging behavior via "${LEGACY_TAGS_CONTEXT_KEY}" context key. This is not encouraged and will be removed in v2.`,
+    );
+  }
+
+  if (useCompatibilityV0Tags(scope)) {
+    Annotations.of(scope).addWarningV2(
+      "@alma-cdk/project@v1:compatibility-v0-tags",
+      `Using @alma-cdk/project@v0 construct's tagging behavior via "${V0_TAGS_CONTEXT_KEY}" context key. You should migrate to using the default tagging behavior as this feature flag will be removed in v2.`,
+    );
+  }
+}

src/project/project.ts

@@ -3,6 +3,7 @@ import { Construct } from "constructs";
 import { Account, ProjectConfiguration } from "./interfaces";
 import { resolveDefaultRegion } from "./resolve-region";
 import { addError } from "../error";
+import { warnAboutDeprecatedTags } from "./deprecation-warnings";
 
 /** Props given to `Project`.
  *
@@ -95,5 +96,7 @@ export class Project extends App {
         [Project.CONTEXT_SCOPE]: config, // and inject project context
       },
     });
+
+    warnAboutDeprecatedTags(this);
   }
 }

src/smartstack/tags/checks.ts

@@ -1,4 +1,3 @@
-import { Construct } from "constructs";
 import { Values } from "./values";
 import { isNonEmptyString } from "../../utils/isNonEmptyString";
 
@@ -9,27 +8,3 @@ export function hasAccount(values: Values): boolean {
 export function hasEnvironment(values: Values): boolean {
   return isNonEmptyString(values.environmentType);
 }
-
-/**
- * Enforces usage of https://github.com/almamedia/alma-cdk-jsii-tag-and-name
- * (for AWS CDK v1) compatible tagging behavior.
- *
- * @deprecated This behavior is not encouraged and will be removed in v2. Additionally according to GitHub search, this is not used anymore.
- */
-export function useLegacyTags(scope: Construct): boolean {
-  const contextKey = "@alma-cdk/project:legacyTags";
-  return scope.node.tryGetContext(contextKey) === true;
-}
-
-/**
- * Compatibility flag for v0 tagging behavior.
- * Due to a bug in v0, the `Contact` and `Organization` tags were NOT applied as they should have.
- * This flag can be used to enforce behavior that matches v0 implementation:
- * I.e. `Contact` and `Organization` tags are NOT applied.
- *
- * @deprecated This behavior is not encouraged and will be removed in v2.
- */
-export function useCompatibilityV0Tags(scope: Construct): boolean {
-  const contextKey = "@alma-cdk/project:compatibility:v0:tags";
-  return scope.node.tryGetContext(contextKey) === true;
-}

src/smartstack/tags/taggers.ts

@@ -1,13 +1,9 @@
 import { Tags } from "aws-cdk-lib";
 import { capitalCase, pascalCase } from "change-case";
 import { Construct } from "constructs";
-import {
-  hasAccount,
-  hasEnvironment,
-  useCompatibilityV0Tags,
-  useLegacyTags,
-} from "./checks";
+import { hasAccount, hasEnvironment } from "./checks";
 import { tagKey, Values } from "./values";
+import * as featureFlags from "../../feature-flags";
 import { isNonEmptyString } from "../../utils/isNonEmptyString";
 
 interface Tagger {
@@ -32,7 +28,7 @@ export const tagEnvironment: Tagger = (
   if (hasEnvironment(values)) {
     tags.add(tagKey.ENVIRONMENT, values.environmentType!);
 
-    if (useLegacyTags(scope)) {
+    if (featureFlags.useLegacyTags(scope)) {
       tags.add(
         tagKey.LEGACY_PROJECT_ENVIRONMENT,
         `${pascalCase(values.projectName)}${pascalCase(values.environmentType!)}`,
@@ -47,7 +43,7 @@ export const tagProject: Tagger = (
   values: Values,
 ) => {
   let value = values.projectName;
-  if (useLegacyTags(scope)) {
+  if (featureFlags.useLegacyTags(scope)) {
     value = capitalCase(values.projectName);
   }
   tags.add(tagKey.PROJECT, value);
@@ -67,7 +63,7 @@ export const tagAuthorOrganization: Tagger = (
   values: Values,
 ) => {
   if (
-    !useCompatibilityV0Tags(scope) &&
+    !featureFlags.useCompatibilityV0Tags(scope) &&
     isNonEmptyString(values.authorOrganization)
   ) {
     tags.add(tagKey.AUTHOR_ORGANIZATION, values.authorOrganization);
@@ -79,7 +75,10 @@ export const tagAuthorEmail: Tagger = (
   tags: Tags,
   values: Values,
 ) => {
-  if (!useCompatibilityV0Tags(scope) && isNonEmptyString(values.authorEmail)) {
+  if (
+    !featureFlags.useCompatibilityV0Tags(scope) &&
+    isNonEmptyString(values.authorEmail)
+  ) {
     tags.add(tagKey.AUTHOR_EMAIL, values.authorEmail);
   }
 };