feat(di): trace usage of legacy APIs slated for deprecation

reportDeprecation() dedups per api+detail and logs at trace level by
default; NS_DEPRECATIONS=warn|error previews the stricter stages so the
same call sites can be escalated over releases. Wired at the external
entry points only: param-name hook invocation, require-time extension
registration, and dynamicCall help templating.

Author: edusperoni

lib/common/deprecation.ts

@@ -0,0 +1,91 @@
+/**
+ * Central reporting point for invocations of legacy/deprecated CLI APIs.
+ *
+ * The severity is a single dial so the same call sites can be staged over
+ * releases: trace (observe usage) → warn (tell users) → error (removal).
+ * `NS_DEPRECATIONS=warn|error` previews a stricter stage ahead of the default.
+ */
+
+type DeprecationStage = "trace" | "warn" | "error";
+
+const DEFAULT_STAGE: DeprecationStage = "trace";
+
+interface IDeprecationLogger {
+	trace(...args: any[]): void;
+	warn(...args: any[]): void;
+}
+
+export interface IDeprecationReport {
+	/** Stable identifier of the deprecated API, e.g. "hooks.param-name-signature". */
+	api: string;
+	/** Distinguishes call sites of one API, e.g. a hook path or extension name. */
+	detail?: string;
+	/**
+	 * Logger to report through. When omitted, the logger is resolved lazily from
+	 * the global injector at call time — never at import time — and the report
+	 * is dropped if no logger is resolvable yet.
+	 */
+	logger?: IDeprecationLogger;
+}
+
+const reported = new Set<string>();
+
+export function reportDeprecation(report: IDeprecationReport): void {
+	const stage = getDeprecationStage();
+	const message = formatMessage(report);
+
+	if (stage === "error") {
+		throw new Error(message);
+	}
+
+	const key = report.detail ? `${report.api}::${report.detail}` : report.api;
+	if (reported.has(key)) {
+		return;
+	}
+	reported.add(key);
+
+	const logger = report.logger || tryResolveGlobalLogger();
+	if (!logger) {
+		return;
+	}
+
+	if (stage === "warn") {
+		logger.warn(message);
+	} else {
+		logger.trace(message);
+	}
+}
+
+/** Test seam: reports are deduplicated once per process otherwise. */
+export function clearReportedDeprecations(): void {
+	reported.clear();
+}
+
+function formatMessage(report: IDeprecationReport): string {
+	const detail = report.detail ? ` (${report.detail})` : "";
+	return (
+		`Legacy CLI API used: ${report.api}${detail}. ` +
+		`This API is planned for deprecation in a future release; ` +
+		`set NS_DEPRECATIONS=warn or NS_DEPRECATIONS=error to preview stricter handling.`
+	);
+}
+
+function getDeprecationStage(): DeprecationStage {
+	const value = (process.env.NS_DEPRECATIONS || "").toLowerCase();
+	if (value === "warn" || value === "error" || value === "trace") {
+		return value;
+	}
+	return DEFAULT_STAGE;
+}
+
+function tryResolveGlobalLogger(): IDeprecationLogger | null {
+	try {
+		const globalInjector = (<any>global).$injector;
+		if (!globalInjector) {
+			return null;
+		}
+		return globalInjector.resolve("logger");
+	} catch (err) {
+		return null;
+	}
+}

lib/common/services/hooks-service.ts

@@ -2,6 +2,7 @@ import * as path from "path";
 import * as util from "util";
 import * as _ from "lodash";
 import { annotate, getValueFromNestedObject } from "../helpers";
+import { reportDeprecation } from "../deprecation";
 import { AnalyticsEventLabelDelimiter } from "../../constants";
 import { IOptions, IPerformanceService } from "../../declarations";
 import {
@@ -245,6 +246,12 @@ export class HooksService implements IHooksService {
 					projectDataHookArg;
 			}
 
+			reportDeprecation({
+				api: "hooks.param-name-signature",
+				detail: hook.fullPath,
+				logger: this.$logger,
+			});
+
 			const maybePromise = this.$injector.resolve(
 				hookEntryPoint,
 				hookArguments,

lib/services/extensibility-service.ts

@@ -3,6 +3,7 @@ import * as _ from "lodash";
 import { cache } from "../common/decorators";
 import * as constants from "../constants";
 import { createRegExp, regExpEscape } from "../common/helpers";
+import { reportDeprecation } from "../common/deprecation";
 import { INodePackageManager, INpmsSingleResultData } from "../declarations";
 import {
 	IFileSystem,
@@ -144,6 +145,11 @@ export class ExtensibilityService implements IExtensibilityService {
 			await this.assertExtensionIsInstalled(extensionName);
 
 			const pathToExtension = this.getPathToExtension(extensionName);
+			reportDeprecation({
+				api: "extensions.require-time-registration",
+				detail: extensionName,
+				logger: this.$logger,
+			});
 			this.$requireService.require(pathToExtension);
 			return this.getInstalledExtensionData(extensionName);
 		} catch (error) {

test/deprecation.ts

@@ -0,0 +1,89 @@
+import { assert } from "chai";
+import { Yok } from "../lib/common/yok";
+import {
+	reportDeprecation,
+	clearReportedDeprecations,
+} from "../lib/common/deprecation";
+import { LoggerStub } from "./stubs";
+
+describe("deprecation tracer", () => {
+	let logger: LoggerStub;
+	let originalEnv: string | undefined;
+
+	beforeEach(() => {
+		logger = new LoggerStub();
+		clearReportedDeprecations();
+		originalEnv = process.env.NS_DEPRECATIONS;
+		delete process.env.NS_DEPRECATIONS;
+	});
+
+	afterEach(() => {
+		if (originalEnv === undefined) {
+			delete process.env.NS_DEPRECATIONS;
+		} else {
+			process.env.NS_DEPRECATIONS = originalEnv;
+		}
+	});
+
+	it("logs at trace level by default and reports once per api+detail", () => {
+		reportDeprecation({ api: "test.api", detail: "site-1", logger });
+		reportDeprecation({ api: "test.api", detail: "site-1", logger });
+
+		const occurrences = logger.traceOutput.split("test.api").length - 1;
+		assert.equal(occurrences, 1);
+		assert.equal(logger.warnOutput, "");
+
+		reportDeprecation({ api: "test.api", detail: "site-2", logger });
+		assert.include(logger.traceOutput, "site-2");
+	});
+
+	it("escalates to warn with NS_DEPRECATIONS=warn", () => {
+		process.env.NS_DEPRECATIONS = "warn";
+
+		reportDeprecation({ api: "test.warn", logger });
+
+		assert.include(logger.warnOutput, "test.warn");
+		assert.equal(logger.traceOutput, "");
+	});
+
+	it("throws with NS_DEPRECATIONS=error — on every call, not just the first", () => {
+		process.env.NS_DEPRECATIONS = "error";
+
+		assert.throws(
+			() => reportDeprecation({ api: "test.error", logger }),
+			/test\.error/,
+		);
+		assert.throws(
+			() => reportDeprecation({ api: "test.error", logger }),
+			/test\.error/,
+		);
+	});
+
+	it("falls back to the global injector's logger when none is passed", () => {
+		const globalAny = <any>global;
+		const previousInjector = globalAny.$injector;
+		const freshInjector = new Yok();
+		const freshLogger = new LoggerStub();
+		freshInjector.register("logger", freshLogger);
+		globalAny.$injector = freshInjector;
+
+		try {
+			reportDeprecation({ api: "test.global-logger" });
+			assert.include(freshLogger.traceOutput, "test.global-logger");
+		} finally {
+			globalAny.$injector = previousInjector;
+		}
+	});
+
+	it("drops the report silently when no logger is resolvable", () => {
+		const globalAny = <any>global;
+		const previousInjector = globalAny.$injector;
+		globalAny.$injector = undefined;
+
+		try {
+			assert.doesNotThrow(() => reportDeprecation({ api: "test.no-logger" }));
+		} finally {
+			globalAny.$injector = previousInjector;
+		}
+	});
+});