feat(#130): starts on creating deprecation warnings on parsing extensions

NOTE that '$git' directive is currently incompatible with being included twice

Author: joelgallant

app-config-default-extensions/index.js

@@ -40,16 +40,18 @@ module.exports = {
       eqDirective(),
       parseDirective(),
       hiddenDirective(),
-      v1Compat(),
       envDirective(aliases, environmentOverride, environmentSourceNames),
       envVarDirective(aliases, environmentOverride, environmentSourceNames),
       extendsDirective(),
       extendsSelfDirective(),
       overrideDirective(),
-      encryptedDirective(symmetricKey),
       timestampDirective(),
       substituteDirective(aliases, environmentOverride, environmentSourceNames),
-      gitRefDirectives(),
+
+      // these will be removed in v3
+      v1Compat(true),
+      gitRefDirectives(undefined, true),
+      encryptedDirective(symmetricKey, true),
     ];
   },
   defaultEnvExtensions() {

app-config-encryption/src/index.ts

@@ -1,16 +1,26 @@
 import type { ParsingExtension } from '@app-config/core';
 import { named } from '@app-config/extension-utils';
+import { logger } from '@app-config/logging';
 import { DecryptedSymmetricKey, decryptValue } from './encryption';
 
 export * from './encryption';
 export * from './secret-agent';
 export * from './secret-agent-tls';
 
 /** Decrypts inline encrypted values */
-export default function encryptedDirective(symmetricKey?: DecryptedSymmetricKey): ParsingExtension {
+export default function encryptedDirective(
+  symmetricKey?: DecryptedSymmetricKey,
+  shouldShowDeprecationNotice?: true,
+): ParsingExtension {
   return named('encryption', (value) => {
     if (typeof value === 'string' && value.startsWith('enc:')) {
       return async (parse) => {
+        if (shouldShowDeprecationNotice) {
+          logger.warn(
+            'Detected deprecated use of @app-config/encryption parsing extension. Please install @app-config/encryption and add it to your meta file "parsingExtensions".',
+          );
+        }
+
         const decrypted = await decryptValue(value, symmetricKey);
 
         return parse(decrypted, { fromSecrets: true, parsedFromEncryptedValue: true });

app-config-git/package.json

@@ -32,6 +32,7 @@
   "dependencies": {
     "@app-config/core": "^2.4.6",
     "@app-config/extension-utils": "^2.4.6",
+    "@app-config/logging": "^2.4.6",
     "simple-git": "2"
   },
   "devDependencies": {

app-config-git/src/index.ts

@@ -1,12 +1,14 @@
 import simpleGit from 'simple-git';
 import { ParsingExtension, AppConfigError, Fallbackable } from '@app-config/core';
 import { named, forKey, validateOptions } from '@app-config/extension-utils';
+import { logger } from '@app-config/logging';
 
 class GitError extends Fallbackable {}
 
 /** Access to the git branch and commit ref */
 export default function gitRefDirectives(
   getStatus: typeof gitStatus = gitStatus,
+  shouldShowDeprecationNotice?: true,
 ): ParsingExtension {
   return named(
     '$git',
@@ -15,6 +17,12 @@ export default function gitRefDirectives(
       validateOptions(
         (SchemaBuilder) => SchemaBuilder.stringSchema(),
         (value) => async (parse) => {
+          if (shouldShowDeprecationNotice) {
+            logger.warn(
+              'Detected deprecated use of @app-config/git parsing extension. Please install @app-config/git and add it to your meta file "parsingExtensions".',
+            );
+          }
+
           switch (value) {
             case 'commit':
               return getStatus().then(({ commitRef }) => parse(commitRef, { shouldFlatten: true }));

app-config-git/tsconfig.json

@@ -9,6 +9,7 @@
   "references": [
     { "path": "../app-config-test-utils" },
     { "path": "../app-config-core" },
+    { "path": "../app-config-logging" },
     { "path": "../app-config-extension-utils" }
   ]
 }

app-config-v1-compat/src/index.ts

@@ -7,7 +7,7 @@ import { FileSource } from '@app-config/node';
 import { logger } from '@app-config/logging';
 
 /** V1 app-config compatibility */
-export default function v1Compat(): ParsingExtension {
+export default function v1Compat(shouldShowDeprecationNotice?: true): ParsingExtension {
   return named('v1-compat', (value, [_, key], context) => {
     // only apply in top-level app-config property
     if (context[context.length - 1]?.[0] !== Root) {
@@ -16,16 +16,6 @@ export default function v1Compat(): ParsingExtension {
 
     if (key === 'app-config' && isObject(value)) {
       return async (parse, _, ctx) => {
-        if (ctx instanceof FileSource) {
-          logger.warn(
-            `Using V1 compatibility layer for special 'app-config' property in ${ctx.filePath}! This functionality is deprecated and may be removed in the future.`,
-          );
-        } else {
-          logger.warn(
-            `Using V1 compatibility layer for special 'app-config' property! This functionality is deprecated and may be removed in the future.`,
-          );
-        }
-
         const resolveAmbiguousFilename = async (filepath: string) => {
           let resolvedPath = filepath;
 
@@ -56,13 +46,25 @@ export default function v1Compat(): ParsingExtension {
         // TODO: multiple properties defined
 
         if ('extends' in value) {
+          if (shouldShowDeprecationNotice) {
+            logger.warn(
+              'Detected deprecated use of @app-config/v1-compat parsing extension. Please install @app-config/v1-compat and add it to your meta file "parsingExtensions".',
+            );
+          }
+
           return parse(
             { $extends: await resolveAmbiguousFilename(value.extends as string) },
             { shouldMerge: true },
           );
         }
 
         if ('extendsOptional' in value) {
+          if (shouldShowDeprecationNotice) {
+            logger.warn(
+              'Detected deprecated use of @app-config/v1-compat parsing extension. Please install @app-config/v1-compat and add it to your meta file "parsingExtensions".',
+            );
+          }
+
           return parse(
             {
               $extends: {
@@ -75,13 +77,25 @@ export default function v1Compat(): ParsingExtension {
         }
 
         if ('override' in value) {
+          if (shouldShowDeprecationNotice) {
+            logger.warn(
+              'Detected deprecated use of @app-config/v1-compat parsing extension. Please install @app-config/v1-compat and add it to your meta file "parsingExtensions".',
+            );
+          }
+
           return parse(
             { $override: await resolveAmbiguousFilename(value.override as string) },
             { shouldOverride: true },
           );
         }
 
         if ('overrideOptional' in value) {
+          if (shouldShowDeprecationNotice) {
+            logger.warn(
+              'Detected deprecated use of @app-config/v1-compat parsing extension. Please install @app-config/v1-compat and add it to your meta file "parsingExtensions".',
+            );
+          }
+
           return parse(
             {
               $override: {