@aws/nx-plugin 1.0.0-rc.6 → 1.0.0-rc.61

package/src/utils/declared-dependencies.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { IPyDepVersion, ITsDepVersion } from './versions';
+/**
+ * Which vended dependencies each generator is responsible for, and when each
+ * applies.
+ *
+ * A generator declares every dependency it may add — including those added on
+ * its behalf by helpers it calls — once, and `addTsDependencies` /
+ * `addPyDependencies` add the subset whose `when` predicate the generator's
+ * metadata satisfies. The declaration is the only place packages are listed.
+ *
+ * The same declaration drives the version sync migration, which replays the
+ * predicates against the metadata recorded on each project. Pass the very object
+ * you record as metadata, so what a generator added and what the migration owns
+ * cannot drift.
+ */
+/**
+ * The metadata a generator records, which its predicates read. Deliberately
+ * `object` rather than an index signature, so a generator can type its
+ * declaration against a plain interface.
+ */
+export type DependencyMetadata = object;
+/** What every declared dependency carries, whichever language it belongs to. */
+export interface DeclaredDependency<Name, M extends DependencyMetadata> {
+    readonly name: Name;
+    /**
+     * Whether this dependency applies. Reads the metadata the generator records,
+     * so the migration can evaluate the same predicate later. Any truthy return
+     * counts, so a predicate can hand back the value it read.
+     */
+    readonly when?: (metadata: M) => unknown;
+    /** Added to the workspace root manifest rather than the project's. */
+    readonly root?: boolean;
+    /**
+     * Declared only so the version sync keeps its pinned version current — an
+     * `overrides` entry, say. Never installed as a dependency.
+     */
+    readonly versionOnly?: boolean;
+}
+/**
+ * A TypeScript dependency, which may be a dev dependency.
+ *
+ * `group` is typed as never-present rather than left off, so putting a Python
+ * flag on a TypeScript entry is a type error instead of an ignored property.
+ */
+export interface DeclaredTsDependency<Name, M extends DependencyMetadata> extends DeclaredDependency<Name, M> {
+    /** Added as a dev dependency rather than a runtime one. */
+    readonly dev?: boolean;
+    readonly group?: never;
+}
+/** A Python dependency, which may belong to a pyproject dependency group. */
+export interface DeclaredPyDependency<Name, M extends DependencyMetadata> extends DeclaredDependency<Name, M> {
+    /** Added to this pyproject dependency group rather than the main list. */
+    readonly group?: string;
+    readonly dev?: never;
+}
+export interface DependencyDeclaration<Ts extends readonly DeclaredTsDependency<ITsDepVersion, never>[] = readonly DeclaredTsDependency<ITsDepVersion, never>[], Py extends readonly DeclaredPyDependency<IPyDepVersion, never>[] = readonly DeclaredPyDependency<IPyDepVersion, never>[]> {
+    readonly ts: Ts;
+    readonly py: Py;
+}
+/**
+ * Declare the dependencies a generator owns, typed against the metadata it
+ * records. Spread the `*_DEPENDENCIES` of any helper called, so the declaration
+ * covers what those helpers add too.
+ */
+export declare const declareDependencies: <M extends DependencyMetadata = Record<string, never>>() => <const Ts extends readonly DeclaredTsDependency<ITsDepVersion, M>[], const Py extends readonly DeclaredPyDependency<IPyDepVersion, M>[]>(declaration: {
+    ts?: Ts;
+    py?: Py;
+}) => DependencyDeclaration<Ts, Py>;
+/**
+ * Narrow entries to a further condition, keeping the one each already carries.
+ *
+ * For a helper's constant spread into a generator that calls it down one branch:
+ * the branch gates the whole set, and each entry's own predicate still gates it
+ * within that branch. Replacing `when` outright would widen ownership to the
+ * helper's every branch.
+ */
+export declare const onlyWhen: <M extends DependencyMetadata, const Entries extends readonly {
+    readonly name: unknown;
+}[]>(entries: Entries, condition: (metadata: M) => unknown) => { readonly [K in keyof Entries]: Omit<Entries[K], "when"> & {
+    when: (m: M) => boolean;
+}; };
+/**
+ * Mark entries as declared for ownership but never installed here — a helper's
+ * constant spread into a generator that doesn't own the project the helper adds
+ * them to.
+ */
+export declare const ownedElsewhere: <const Entries extends readonly unknown[]>(entries: Entries) => { readonly [K in keyof Entries]: Entries[K] & {
+    versionOnly: true;
+}; };
+/** Every package a declaration names, whatever its predicate. */
+export declare const declaredNames: <Name>(entries: readonly {
+    readonly name: Name;
+}[]) => Name[];
+/**
+ * The entries of a declaration whose condition the given metadata satisfies —
+ * everything this occurrence is responsible for, installed here or not.
+ *
+ * A predicate that throws — reading a field the metadata doesn't carry, say —
+ * counts as not applying. The migration evaluates these against whatever a
+ * project happened to record, and must not claim a branch it cannot confirm.
+ */
+export declare const ownedDependencyEntries: <Name, M extends DependencyMetadata, Entry extends DeclaredDependency<Name, M>>(entries: readonly Entry[], metadata: M) => Entry[];
+/**
+ * The entries to install for the given metadata: those it owns, less the ones
+ * declared for their version alone. A `versionOnly` entry is still owned — the
+ * sync keeps its pin current wherever it already sits.
+ */
+export declare const applicableDependencies: <Name, M extends DependencyMetadata, Entry extends DeclaredDependency<Name, M>>(entries: readonly Entry[], metadata: M) => Entry[];
+/**
+ * Requires a caller's declaration to cover `Needed`, naming whatever is missing
+ * in the type error. Helpers that add dependencies take this alongside the
+ * declaration so a forgotten spread can't compile.
+ */
+export type MustDeclare<Needed extends readonly {
+    readonly name: ITsDepVersion;
+}[], D extends DependencyDeclaration> = [Exclude<Needed[number]['name'], D['ts'][number]['name']>] extends [never] ? unknown : {
+    __missingDeclaredDependencies: Exclude<Needed[number]['name'], D['ts'][number]['name']>;
+};
+/** `MustDeclare` for Python dependencies. */
+export type MustDeclarePy<Needed extends readonly {
+    readonly name: IPyDepVersion;
+}[], D extends DependencyDeclaration> = [Exclude<Needed[number]['name'], D['py'][number]['name']>] extends [never] ? unknown : {
+    __missingDeclaredPyDependencies: Exclude<Needed[number]['name'], D['py'][number]['name']>;
+};
+/**
+ * The dependencies a declaration covers, for typing a conditional list without
+ * widening it to every vended package.
+ */
+export type DeclaredTs<D extends DependencyDeclaration> = D['ts'][number]['name'];
+/** `DeclaredTs` for Python dependencies. */
+export type DeclaredPy<D extends DependencyDeclaration> = D['py'][number]['name'];
+/**
+ * Narrows a caller's declaration to the subset a helper adds, which
+ * `MustDeclare` has already proven the caller covers.
+ */
+export declare const forDependencies: <const Ts extends readonly DeclaredDependency<ITsDepVersion, never>[] = [], const Py extends readonly DeclaredDependency<IPyDepVersion, never>[] = []>(declaration: DependencyDeclaration) => DependencyDeclaration<Ts, Py>;

package/src/utils/declared-dependencies.js

@@ -0,0 +1,64 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */ /**
+ * Declare the dependencies a generator owns, typed against the metadata it
+ * records. Spread the `*_DEPENDENCIES` of any helper called, so the declaration
+ * covers what those helpers add too.
+ */ export const declareDependencies = ()=>(declaration)=>({
+            ts: declaration.ts ?? [],
+            py: declaration.py ?? []
+        });
+/**
+ * Narrow entries to a further condition, keeping the one each already carries.
+ *
+ * For a helper's constant spread into a generator that calls it down one branch:
+ * the branch gates the whole set, and each entry's own predicate still gates it
+ * within that branch. Replacing `when` outright would widen ownership to the
+ * helper's every branch.
+ */ export const onlyWhen = (entries, condition)=>entries.map((entry)=>{
+        // A declaration erases the metadata its predicates read, so calling one back
+        // requires naming the type the caller narrows to.
+        const own = entry.when;
+        return {
+            ...entry,
+            when: (metadata)=>Boolean(condition(metadata)) && Boolean(own?.(metadata) ?? true)
+        };
+    });
+/**
+ * Mark entries as declared for ownership but never installed here — a helper's
+ * constant spread into a generator that doesn't own the project the helper adds
+ * them to.
+ */ export const ownedElsewhere = (entries)=>entries.map((entry)=>({
+            ...entry,
+            versionOnly: true
+        }));
+/** Every package a declaration names, whatever its predicate. */ export const declaredNames = (entries)=>entries.map((entry)=>entry.name);
+/**
+ * The entries of a declaration whose condition the given metadata satisfies —
+ * everything this occurrence is responsible for, installed here or not.
+ *
+ * A predicate that throws — reading a field the metadata doesn't carry, say —
+ * counts as not applying. The migration evaluates these against whatever a
+ * project happened to record, and must not claim a branch it cannot confirm.
+ */ export const ownedDependencyEntries = (entries, metadata)=>entries.filter((entry)=>{
+        if (!entry.when) {
+            return true;
+        }
+        try {
+            return Boolean(entry.when(metadata));
+        } catch  {
+            return false;
+        }
+    });
+/**
+ * The entries to install for the given metadata: those it owns, less the ones
+ * declared for their version alone. A `versionOnly` entry is still owned — the
+ * sync keeps its pin current wherever it already sits.
+ */ export const applicableDependencies = (entries, metadata)=>ownedDependencyEntries(entries, metadata).filter((entry)=>!entry.versionOnly);
+/**
+ * Narrows a caller's declaration to the subset a helper adds, which
+ * `MustDeclare` has already proven the caller covers.
+ */ export const forDependencies = (declaration)=>declaration;
+
+//# sourceMappingURL=declared-dependencies.js.map

package/src/utils/declared-dependencies.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../packages/nx-plugin/src/utils/declared-dependencies.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport type { IPyDepVersion, ITsDepVersion } from './versions';\n\n/**\n * Which vended dependencies each generator is responsible for, and when each\n * applies.\n *\n * A generator declares every dependency it may add — including those added on\n * its behalf by helpers it calls — once, and `addTsDependencies` /\n * `addPyDependencies` add the subset whose `when` predicate the generator's\n * metadata satisfies. The declaration is the only place packages are listed.\n *\n * The same declaration drives the version sync migration, which replays the\n * predicates against the metadata recorded on each project. Pass the very object\n * you record as metadata, so what a generator added and what the migration owns\n * cannot drift.\n */\n\n/**\n * The metadata a generator records, which its predicates read. Deliberately\n * `object` rather than an index signature, so a generator can type its\n * declaration against a plain interface.\n */\nexport type DependencyMetadata = object;\n\n/** What every declared dependency carries, whichever language it belongs to. */\nexport interface DeclaredDependency<Name, M extends DependencyMetadata> {\n  readonly name: Name;\n  /**\n   * Whether this dependency applies. Reads the metadata the generator records,\n   * so the migration can evaluate the same predicate later. Any truthy return\n   * counts, so a predicate can hand back the value it read.\n   */\n  readonly when?: (metadata: M) => unknown;\n  /** Added to the workspace root manifest rather than the project's. */\n  readonly root?: boolean;\n  /**\n   * Declared only so the version sync keeps its pinned version current — an\n   * `overrides` entry, say. Never installed as a dependency.\n   */\n  readonly versionOnly?: boolean;\n}\n\n/**\n * A TypeScript dependency, which may be a dev dependency.\n *\n * `group` is typed as never-present rather than left off, so putting a Python\n * flag on a TypeScript entry is a type error instead of an ignored property.\n */\nexport interface DeclaredTsDependency<Name, M extends DependencyMetadata>\n  extends DeclaredDependency<Name, M> {\n  /** Added as a dev dependency rather than a runtime one. */\n  readonly dev?: boolean;\n  readonly group?: never;\n}\n\n/** A Python dependency, which may belong to a pyproject dependency group. */\nexport interface DeclaredPyDependency<Name, M extends DependencyMetadata>\n  extends DeclaredDependency<Name, M> {\n  /** Added to this pyproject dependency group rather than the main list. */\n  readonly group?: string;\n  readonly dev?: never;\n}\n\nexport interface DependencyDeclaration<\n  Ts extends readonly DeclaredTsDependency<\n    ITsDepVersion,\n    never\n  >[] = readonly DeclaredTsDependency<ITsDepVersion, never>[],\n  Py extends readonly DeclaredPyDependency<\n    IPyDepVersion,\n    never\n  >[] = readonly DeclaredPyDependency<IPyDepVersion, never>[],\n> {\n  readonly ts: Ts;\n  readonly py: Py;\n}\n\n/**\n * Declare the dependencies a generator owns, typed against the metadata it\n * records. Spread the `*_DEPENDENCIES` of any helper called, so the declaration\n * covers what those helpers add too.\n */\nexport const declareDependencies =\n  <M extends DependencyMetadata = Record<string, never>>() =>\n  <\n    const Ts extends readonly DeclaredTsDependency<ITsDepVersion, M>[],\n    const Py extends readonly DeclaredPyDependency<IPyDepVersion, M>[],\n  >(declaration: {\n    ts?: Ts;\n    py?: Py;\n  }): DependencyDeclaration<Ts, Py> =>\n    ({\n      ts: declaration.ts ?? [],\n      py: declaration.py ?? [],\n    }) as unknown as DependencyDeclaration<Ts, Py>;\n\n/**\n * Narrow entries to a further condition, keeping the one each already carries.\n *\n * For a helper's constant spread into a generator that calls it down one branch:\n * the branch gates the whole set, and each entry's own predicate still gates it\n * within that branch. Replacing `when` outright would widen ownership to the\n * helper's every branch.\n */\nexport const onlyWhen = <\n  M extends DependencyMetadata,\n  const Entries extends readonly { readonly name: unknown }[],\n>(\n  entries: Entries,\n  condition: (metadata: M) => unknown,\n): {\n  readonly [K in keyof Entries]: Omit<Entries[K], 'when'> & {\n    when: (m: M) => boolean;\n  };\n} =>\n  entries.map((entry) => {\n    // A declaration erases the metadata its predicates read, so calling one back\n    // requires naming the type the caller narrows to.\n    const own = (entry as { when?: (m: M) => unknown }).when;\n    return {\n      ...entry,\n      when: (metadata: M) =>\n        Boolean(condition(metadata)) && Boolean(own?.(metadata) ?? true),\n    };\n  }) as never;\n\n/**\n * Mark entries as declared for ownership but never installed here — a helper's\n * constant spread into a generator that doesn't own the project the helper adds\n * them to.\n */\nexport const ownedElsewhere = <const Entries extends readonly unknown[]>(\n  entries: Entries,\n): { readonly [K in keyof Entries]: Entries[K] & { versionOnly: true } } =>\n  entries.map((entry) => ({\n    ...(entry as object),\n    versionOnly: true,\n  })) as never;\n\n/** Every package a declaration names, whatever its predicate. */\nexport const declaredNames = <Name>(\n  entries: readonly { readonly name: Name }[],\n): Name[] => entries.map((entry) => entry.name);\n\n/**\n * The entries of a declaration whose condition the given metadata satisfies —\n * everything this occurrence is responsible for, installed here or not.\n *\n * A predicate that throws — reading a field the metadata doesn't carry, say —\n * counts as not applying. The migration evaluates these against whatever a\n * project happened to record, and must not claim a branch it cannot confirm.\n */\nexport const ownedDependencyEntries = <\n  Name,\n  M extends DependencyMetadata,\n  Entry extends DeclaredDependency<Name, M>,\n>(\n  entries: readonly Entry[],\n  metadata: M,\n): Entry[] =>\n  entries.filter((entry) => {\n    if (!entry.when) {\n      return true;\n    }\n    try {\n      return Boolean(entry.when(metadata));\n    } catch {\n      return false;\n    }\n  });\n\n/**\n * The entries to install for the given metadata: those it owns, less the ones\n * declared for their version alone. A `versionOnly` entry is still owned — the\n * sync keeps its pin current wherever it already sits.\n */\nexport const applicableDependencies = <\n  Name,\n  M extends DependencyMetadata,\n  Entry extends DeclaredDependency<Name, M>,\n>(\n  entries: readonly Entry[],\n  metadata: M,\n): Entry[] =>\n  ownedDependencyEntries(entries, metadata).filter(\n    (entry) => !entry.versionOnly,\n  );\n\n/**\n * Requires a caller's declaration to cover `Needed`, naming whatever is missing\n * in the type error. Helpers that add dependencies take this alongside the\n * declaration so a forgotten spread can't compile.\n */\nexport type MustDeclare<\n  Needed extends readonly { readonly name: ITsDepVersion }[],\n  D extends DependencyDeclaration,\n> = [Exclude<Needed[number]['name'], D['ts'][number]['name']>] extends [never]\n  ? unknown\n  : {\n      __missingDeclaredDependencies: Exclude<\n        Needed[number]['name'],\n        D['ts'][number]['name']\n      >;\n    };\n\n/** `MustDeclare` for Python dependencies. */\nexport type MustDeclarePy<\n  Needed extends readonly { readonly name: IPyDepVersion }[],\n  D extends DependencyDeclaration,\n> = [Exclude<Needed[number]['name'], D['py'][number]['name']>] extends [never]\n  ? unknown\n  : {\n      __missingDeclaredPyDependencies: Exclude<\n        Needed[number]['name'],\n        D['py'][number]['name']\n      >;\n    };\n\n/**\n * The dependencies a declaration covers, for typing a conditional list without\n * widening it to every vended package.\n */\nexport type DeclaredTs<D extends DependencyDeclaration> =\n  D['ts'][number]['name'];\n\n/** `DeclaredTs` for Python dependencies. */\nexport type DeclaredPy<D extends DependencyDeclaration> =\n  D['py'][number]['name'];\n\n/**\n * Narrows a caller's declaration to the subset a helper adds, which\n * `MustDeclare` has already proven the caller covers.\n */\nexport const forDependencies = <\n  const Ts extends readonly DeclaredDependency<ITsDepVersion, never>[] = [],\n  const Py extends readonly DeclaredDependency<IPyDepVersion, never>[] = [],\n>(\n  declaration: DependencyDeclaration,\n): DependencyDeclaration<Ts, Py> =>\n  declaration as unknown as DependencyDeclaration<Ts, Py>;\n"],"names":["declareDependencies","declaration","ts","py","onlyWhen","entries","condition","map","entry","own","when","metadata","Boolean","ownedElsewhere","versionOnly","declaredNames","name","ownedDependencyEntries","filter","applicableDependencies","forDependencies"],"mappings":"AAAA;;;CAGC,GA8ED;;;;CAIC,GACD,OAAO,MAAMA,sBACX,IACA,CAGEC,cAIC,CAAA;YACCC,IAAID,YAAYC,EAAE,IAAI,EAAE;YACxBC,IAAIF,YAAYE,EAAE,IAAI,EAAE;QAC1B,CAAA,EAA+C;AAEnD;;;;;;;CAOC,GACD,OAAO,MAAMC,WAAW,CAItBC,SACAC,YAMAD,QAAQE,GAAG,CAAC,CAACC;QACX,6EAA6E;QAC7E,kDAAkD;QAClD,MAAMC,MAAM,AAACD,MAAuCE,IAAI;QACxD,OAAO;YACL,GAAGF,KAAK;YACRE,MAAM,CAACC,WACLC,QAAQN,UAAUK,cAAcC,QAAQH,MAAME,aAAa;QAC/D;IACF,GAAY;AAEd;;;;CAIC,GACD,OAAO,MAAME,iBAAiB,CAC5BR,UAEAA,QAAQE,GAAG,CAAC,CAACC,QAAW,CAAA;YACtB,GAAIA,KAAK;YACTM,aAAa;QACf,CAAA,GAAa;AAEf,+DAA+D,GAC/D,OAAO,MAAMC,gBAAgB,CAC3BV,UACWA,QAAQE,GAAG,CAAC,CAACC,QAAUA,MAAMQ,IAAI,EAAE;AAEhD;;;;;;;CAOC,GACD,OAAO,MAAMC,yBAAyB,CAKpCZ,SACAM,WAEAN,QAAQa,MAAM,CAAC,CAACV;QACd,IAAI,CAACA,MAAME,IAAI,EAAE;YACf,OAAO;QACT;QACA,IAAI;YACF,OAAOE,QAAQJ,MAAME,IAAI,CAACC;QAC5B,EAAE,OAAM;YACN,OAAO;QACT;IACF,GAAG;AAEL;;;;CAIC,GACD,OAAO,MAAMQ,yBAAyB,CAKpCd,SACAM,WAEAM,uBAAuBZ,SAASM,UAAUO,MAAM,CAC9C,CAACV,QAAU,CAACA,MAAMM,WAAW,EAC7B;AA2CJ;;;CAGC,GACD,OAAO,MAAMM,kBAAkB,CAI7BnB,cAEAA,YAAwD"}

package/src/utils/dependencies.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { type GeneratorCallback, type PackageManager, type Tree } from '@nx/devkit';
+export declare const detectWorkspacePackageManager: (tree: Tree) => PackageManager;
+/** Clears the catalog support cache. Only needed by tests. */
+export declare const resetCatalogSupportCache: () => void;
+export declare const getLocalDependencySpecifier: (tree: Tree) => string;
+export declare const supportsCatalogs: (tree: Tree) => boolean;
+export declare const catalogsEnabled: (tree: Tree) => boolean;
+/**
+ * Drop-in replacement for devkit's `addDependenciesToPackageJson` that records
+ * versions in the package manager's catalog when enabled. Callers pass a
+ * project manifest path for runtime deps (so `noUndeclaredDependencies` passes)
+ * and the root for shared tooling.
+ */
+export declare const addDependenciesToPackageJson: (tree: Tree, dependencies: Record<string, string>, devDependencies: Record<string, string>, packageJsonPath?: string) => GeneratorCallback;

package/src/utils/dependencies.js

@@ -0,0 +1,206 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */ import { detectPackageManager, addDependenciesToPackageJson as devkitAddDependenciesToPackageJson, getPackageManagerVersion, readJson, updateJson } from "@nx/devkit";
+import yaml from "js-yaml";
+import { coerce, gt, gte } from "semver";
+import { readAwsNxPluginConfig } from "./config/utils.js";
+// Minimum version that introduced catalog support per package manager (npm has none).
+const CATALOG_SUPPORT = {
+    pnpm: '9.5.0',
+    yarn: '4.10.0',
+    bun: '1.2.14'
+};
+// Prefer tree markers over devkit's `detectPackageManager`, which reads the
+// real filesystem and is nondeterministic for virtual trees in tests.
+export const detectWorkspacePackageManager = (tree)=>tree.exists('pnpm-workspace.yaml') ? 'pnpm' : detectPackageManager(tree.root);
+// Coerce a single simple range to a version. Rejects compound ranges
+// (whitespace / `||`), which coerce would silently reduce, plus tags/protocols.
+const parseSimpleRange = (version)=>{
+    const trimmed = version.trim();
+    if (/\s|\|\|/.test(trimmed)) {
+        return undefined;
+    }
+    return coerce(trimmed, {
+        includePrerelease: true
+    }) ?? undefined;
+};
+const versionAtLeast = (version, minimum)=>gte(parseSimpleRange(version) ?? '0.0.0', parseSimpleRange(minimum) ?? '0.0.0');
+// Only a strict upgrade replaces an existing catalog entry, so generating a
+// project never downgrades a version the user raised. Uncomparable entries
+// (tags, complex ranges) are kept.
+const isVersionUpgrade = (incoming, existing)=>{
+    const existingParsed = parseSimpleRange(existing);
+    const incomingParsed = parseSimpleRange(incoming);
+    if (!existingParsed || !incomingParsed) {
+        return false;
+    }
+    return gt(incomingParsed, existingParsed);
+};
+// Keyed by root + package manager; detecting support shells out for a version.
+const catalogSupportCache = new Map();
+/** Clears the catalog support cache. Only needed by tests. */ export const resetCatalogSupportCache = ()=>{
+    catalogSupportCache.clear();
+};
+// Local-project specifier: the `workspace:` protocol where supported (pnpm,
+// bun, yarn berry), `*` on npm and yarn classic which reject it.
+export const getLocalDependencySpecifier = (tree)=>{
+    const packageManager = detectWorkspacePackageManager(tree);
+    if (packageManager === 'npm') {
+        return '*';
+    }
+    if (packageManager === 'yarn') {
+        let major = 2;
+        try {
+            major = Number.parseInt(getPackageManagerVersion('yarn', tree.root).split('.')[0], 10);
+        } catch  {
+        // Not installed (e.g. tests) — assume berry.
+        }
+        if (major < 2) {
+            return '*';
+        }
+    }
+    return 'workspace:*';
+};
+export const supportsCatalogs = (tree)=>{
+    const packageManager = detectWorkspacePackageManager(tree);
+    const cacheKey = `${tree.root}|${packageManager}`;
+    const cached = catalogSupportCache.get(cacheKey);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const minimumVersion = CATALOG_SUPPORT[packageManager];
+    let supported = false;
+    if (minimumVersion) {
+        try {
+            supported = versionAtLeast(getPackageManagerVersion(packageManager, tree.root), minimumVersion);
+        } catch  {
+            // Not installed (e.g. tests) — assume a modern version.
+            supported = true;
+        }
+    }
+    catalogSupportCache.set(cacheKey, supported);
+    return supported;
+};
+// True when the package manager supports catalogs and the workspace hasn't
+// opted out via `packageManager.catalogs: false` in aws-nx-plugin.config.mts.
+export const catalogsEnabled = (tree)=>{
+    if (!supportsCatalogs(tree)) {
+        return false;
+    }
+    const config = readAwsNxPluginConfig(tree);
+    return config?.packageManager?.catalogs !== false;
+};
+/**
+ * Drop-in replacement for devkit's `addDependenciesToPackageJson` that records
+ * versions in the package manager's catalog when enabled. Callers pass a
+ * project manifest path for runtime deps (so `noUndeclaredDependencies` passes)
+ * and the root for shared tooling.
+ */ export const addDependenciesToPackageJson = (tree, dependencies, devDependencies, packageJsonPath = 'package.json')=>{
+    const callback = devkitAddDependenciesToPackageJson(tree, dependencies, devDependencies, packageJsonPath);
+    if (catalogsEnabled(tree)) {
+        const packageNames = [
+            ...Object.keys(dependencies),
+            ...Object.keys(devDependencies)
+        ];
+        convertDependenciesToCatalog(tree, packageJsonPath, packageNames);
+        // Convert any matching root ranges Nx wrote behind our back (e.g.
+        // `@types/node`, `react`) so they don't resolve to a second copy alongside
+        // the catalog version. Skipped when the caller already targeted the root.
+        if (packageJsonPath !== 'package.json') {
+            convertDependenciesToCatalog(tree, 'package.json', packageNames);
+        }
+    }
+    return callback;
+};
+// Nx generators read these versions from the root manifest and coerce without
+// a null guard; Nx ships no bun catalog manager, so an unresolved `catalog:`
+// crashes them. Keep direct ranges on bun (react-dom pinned with react).
+const BUN_INTROSPECTED_PACKAGES = new Set([
+    'vite',
+    'react',
+    'react-dom'
+]);
+const isCatalogExcluded = (tree, packageName)=>detectWorkspacePackageManager(tree) === 'bun' && BUN_INTROSPECTED_PACKAGES.has(packageName);
+// Convert direct version ranges to `catalog:` references in a single manifest
+// and record the range in the workspace catalog. Protocol specifiers
+// (catalog:/workspace:/...) are left alone.
+const convertDependenciesToCatalog = (tree, packageJsonPath, packageNames)=>{
+    const catalogUpdates = {};
+    updateJson(tree, packageJsonPath, (json)=>{
+        for (const field of [
+            'dependencies',
+            'devDependencies'
+        ]){
+            for (const packageName of packageNames){
+                const version = json[field]?.[packageName];
+                if (version && !version.includes(':') && !isCatalogExcluded(tree, packageName)) {
+                    catalogUpdates[packageName] = version;
+                    json[field][packageName] = 'catalog:';
+                }
+            }
+        }
+        return json;
+    });
+    if (Object.keys(catalogUpdates).length > 0) {
+        writeCatalogVersions(tree, catalogUpdates);
+    }
+};
+// Record ranges in the default catalog, creating it if absent. Only strict
+// upgrades replace existing entries (see `isVersionUpgrade`).
+const writeCatalogVersions = (tree, updates)=>{
+    const applyUpdates = (catalog)=>{
+        const existing = catalog ?? {};
+        const applicable = Object.fromEntries(Object.entries(updates).filter(([name, version])=>existing[name] === undefined || isVersionUpgrade(version, existing[name])));
+        if (Object.keys(applicable).length === 0) {
+            return undefined;
+        }
+        return {
+            ...existing,
+            ...applicable
+        };
+    };
+    switch(detectWorkspacePackageManager(tree)){
+        case 'pnpm':
+            {
+                const workspaceYaml = yaml.load(tree.read('pnpm-workspace.yaml', 'utf-8') ?? '') ?? {};
+                const catalog = applyUpdates(workspaceYaml.catalog);
+                if (catalog) {
+                    tree.write('pnpm-workspace.yaml', yaml.dump({
+                        ...workspaceYaml,
+                        catalog
+                    }, {
+                        quotingType: "'"
+                    }));
+                }
+                break;
+            }
+        case 'yarn':
+            {
+                const yarnRc = yaml.load(tree.read('.yarnrc.yml', 'utf-8') ?? '') ?? {};
+                const catalog = applyUpdates(yarnRc.catalog);
+                if (catalog) {
+                    tree.write('.yarnrc.yml', yaml.dump({
+                        ...yarnRc,
+                        catalog
+                    }, {
+                        quotingType: "'"
+                    }));
+                }
+                break;
+            }
+        case 'bun':
+            {
+                const catalog = applyUpdates(readJson(tree, 'package.json').catalog);
+                if (catalog) {
+                    updateJson(tree, 'package.json', (json)=>({
+                            ...json,
+                            catalog
+                        }));
+                }
+                break;
+            }
+    }
+};
+
+//# sourceMappingURL=dependencies.js.map

package/src/utils/dependencies.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../packages/nx-plugin/src/utils/dependencies.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport {\n  detectPackageManager,\n  addDependenciesToPackageJson as devkitAddDependenciesToPackageJson,\n  type GeneratorCallback,\n  getPackageManagerVersion,\n  type PackageManager,\n  readJson,\n  type Tree,\n  updateJson,\n} from '@nx/devkit';\nimport yaml from 'js-yaml';\nimport { coerce, gt, gte } from 'semver';\nimport { readAwsNxPluginConfig } from './config/utils';\n\n// Minimum version that introduced catalog support per package manager (npm has none).\nconst CATALOG_SUPPORT: Partial<Record<PackageManager, string>> = {\n  pnpm: '9.5.0',\n  yarn: '4.10.0',\n  bun: '1.2.14',\n};\n\n// Prefer tree markers over devkit's `detectPackageManager`, which reads the\n// real filesystem and is nondeterministic for virtual trees in tests.\nexport const detectWorkspacePackageManager = (tree: Tree): PackageManager =>\n  tree.exists('pnpm-workspace.yaml') ? 'pnpm' : detectPackageManager(tree.root);\n\n// Coerce a single simple range to a version. Rejects compound ranges\n// (whitespace / `||`), which coerce would silently reduce, plus tags/protocols.\nconst parseSimpleRange = (version: string) => {\n  const trimmed = version.trim();\n  if (/\\s|\\|\\|/.test(trimmed)) {\n    return undefined;\n  }\n  return coerce(trimmed, { includePrerelease: true }) ?? undefined;\n};\n\nconst versionAtLeast = (version: string, minimum: string): boolean =>\n  gte(\n    parseSimpleRange(version) ?? '0.0.0',\n    parseSimpleRange(minimum) ?? '0.0.0',\n  );\n\n// Only a strict upgrade replaces an existing catalog entry, so generating a\n// project never downgrades a version the user raised. Uncomparable entries\n// (tags, complex ranges) are kept.\nconst isVersionUpgrade = (incoming: string, existing: string): boolean => {\n  const existingParsed = parseSimpleRange(existing);\n  const incomingParsed = parseSimpleRange(incoming);\n  if (!existingParsed || !incomingParsed) {\n    return false;\n  }\n  return gt(incomingParsed, existingParsed);\n};\n\n// Keyed by root + package manager; detecting support shells out for a version.\nconst catalogSupportCache = new Map<string, boolean>();\n\n/** Clears the catalog support cache. Only needed by tests. */\nexport const resetCatalogSupportCache = (): void => {\n  catalogSupportCache.clear();\n};\n\n// Local-project specifier: the `workspace:` protocol where supported (pnpm,\n// bun, yarn berry), `*` on npm and yarn classic which reject it.\nexport const getLocalDependencySpecifier = (tree: Tree): string => {\n  const packageManager = detectWorkspacePackageManager(tree);\n  if (packageManager === 'npm') {\n    return '*';\n  }\n  if (packageManager === 'yarn') {\n    let major = 2;\n    try {\n      major = Number.parseInt(\n        getPackageManagerVersion('yarn', tree.root).split('.')[0],\n        10,\n      );\n    } catch {\n      // Not installed (e.g. tests) — assume berry.\n    }\n    if (major < 2) {\n      return '*';\n    }\n  }\n  return 'workspace:*';\n};\n\nexport const supportsCatalogs = (tree: Tree): boolean => {\n  const packageManager = detectWorkspacePackageManager(tree);\n  const cacheKey = `${tree.root}|${packageManager}`;\n  const cached = catalogSupportCache.get(cacheKey);\n  if (cached !== undefined) {\n    return cached;\n  }\n  const minimumVersion = CATALOG_SUPPORT[packageManager];\n  let supported = false;\n  if (minimumVersion) {\n    try {\n      supported = versionAtLeast(\n        getPackageManagerVersion(packageManager, tree.root),\n        minimumVersion,\n      );\n    } catch {\n      // Not installed (e.g. tests) — assume a modern version.\n      supported = true;\n    }\n  }\n  catalogSupportCache.set(cacheKey, supported);\n  return supported;\n};\n\n// True when the package manager supports catalogs and the workspace hasn't\n// opted out via `packageManager.catalogs: false` in aws-nx-plugin.config.mts.\nexport const catalogsEnabled = (tree: Tree): boolean => {\n  if (!supportsCatalogs(tree)) {\n    return false;\n  }\n  const config = readAwsNxPluginConfig(tree);\n  return config?.packageManager?.catalogs !== false;\n};\n\n/**\n * Drop-in replacement for devkit's `addDependenciesToPackageJson` that records\n * versions in the package manager's catalog when enabled. Callers pass a\n * project manifest path for runtime deps (so `noUndeclaredDependencies` passes)\n * and the root for shared tooling.\n */\nexport const addDependenciesToPackageJson = (\n  tree: Tree,\n  dependencies: Record<string, string>,\n  devDependencies: Record<string, string>,\n  packageJsonPath = 'package.json',\n): GeneratorCallback => {\n  const callback = devkitAddDependenciesToPackageJson(\n    tree,\n    dependencies,\n    devDependencies,\n    packageJsonPath,\n  );\n\n  if (catalogsEnabled(tree)) {\n    const packageNames = [\n      ...Object.keys(dependencies),\n      ...Object.keys(devDependencies),\n    ];\n    convertDependenciesToCatalog(tree, packageJsonPath, packageNames);\n    // Convert any matching root ranges Nx wrote behind our back (e.g.\n    // `@types/node`, `react`) so they don't resolve to a second copy alongside\n    // the catalog version. Skipped when the caller already targeted the root.\n    if (packageJsonPath !== 'package.json') {\n      convertDependenciesToCatalog(tree, 'package.json', packageNames);\n    }\n  }\n\n  return callback;\n};\n\n// Nx generators read these versions from the root manifest and coerce without\n// a null guard; Nx ships no bun catalog manager, so an unresolved `catalog:`\n// crashes them. Keep direct ranges on bun (react-dom pinned with react).\nconst BUN_INTROSPECTED_PACKAGES = new Set<string>([\n  'vite',\n  'react',\n  'react-dom',\n]);\n\nconst isCatalogExcluded = (tree: Tree, packageName: string): boolean =>\n  detectWorkspacePackageManager(tree) === 'bun' &&\n  BUN_INTROSPECTED_PACKAGES.has(packageName);\n\n// Convert direct version ranges to `catalog:` references in a single manifest\n// and record the range in the workspace catalog. Protocol specifiers\n// (catalog:/workspace:/...) are left alone.\nconst convertDependenciesToCatalog = (\n  tree: Tree,\n  packageJsonPath: string,\n  packageNames: string[],\n): void => {\n  const catalogUpdates: Record<string, string> = {};\n\n  updateJson(tree, packageJsonPath, (json) => {\n    for (const field of ['dependencies', 'devDependencies'] as const) {\n      for (const packageName of packageNames) {\n        const version = json[field]?.[packageName];\n        if (\n          version &&\n          !version.includes(':') &&\n          !isCatalogExcluded(tree, packageName)\n        ) {\n          catalogUpdates[packageName] = version;\n          json[field][packageName] = 'catalog:';\n        }\n      }\n    }\n    return json;\n  });\n\n  if (Object.keys(catalogUpdates).length > 0) {\n    writeCatalogVersions(tree, catalogUpdates);\n  }\n};\n\n// Record ranges in the default catalog, creating it if absent. Only strict\n// upgrades replace existing entries (see `isVersionUpgrade`).\nconst writeCatalogVersions = (\n  tree: Tree,\n  updates: Record<string, string>,\n): void => {\n  const applyUpdates = (\n    catalog: Record<string, string> | undefined,\n  ): Record<string, string> | undefined => {\n    const existing = catalog ?? {};\n    const applicable = Object.fromEntries(\n      Object.entries(updates).filter(\n        ([name, version]) =>\n          existing[name] === undefined ||\n          isVersionUpgrade(version, existing[name]),\n      ),\n    );\n    if (Object.keys(applicable).length === 0) {\n      return undefined;\n    }\n    return { ...existing, ...applicable };\n  };\n\n  switch (detectWorkspacePackageManager(tree)) {\n    case 'pnpm': {\n      const workspaceYaml =\n        (yaml.load(tree.read('pnpm-workspace.yaml', 'utf-8') ?? '') as Record<\n          string,\n          unknown\n        >) ?? {};\n      const catalog = applyUpdates(\n        workspaceYaml.catalog as Record<string, string> | undefined,\n      );\n      if (catalog) {\n        tree.write(\n          'pnpm-workspace.yaml',\n          yaml.dump({ ...workspaceYaml, catalog }, { quotingType: \"'\" }),\n        );\n      }\n      break;\n    }\n    case 'yarn': {\n      const yarnRc =\n        (yaml.load(tree.read('.yarnrc.yml', 'utf-8') ?? '') as Record<\n          string,\n          unknown\n        >) ?? {};\n      const catalog = applyUpdates(\n        yarnRc.catalog as Record<string, string> | undefined,\n      );\n      if (catalog) {\n        tree.write(\n          '.yarnrc.yml',\n          yaml.dump({ ...yarnRc, catalog }, { quotingType: \"'\" }),\n        );\n      }\n      break;\n    }\n    case 'bun': {\n      const catalog = applyUpdates(\n        readJson<{ catalog?: Record<string, string> }>(tree, 'package.json')\n          .catalog,\n      );\n      if (catalog) {\n        updateJson(tree, 'package.json', (json) => ({ ...json, catalog }));\n      }\n      break;\n    }\n  }\n};\n"],"names":["detectPackageManager","addDependenciesToPackageJson","devkitAddDependenciesToPackageJson","getPackageManagerVersion","readJson","updateJson","yaml","coerce","gt","gte","readAwsNxPluginConfig","CATALOG_SUPPORT","pnpm","yarn","bun","detectWorkspacePackageManager","tree","exists","root","parseSimpleRange","version","trimmed","trim","test","undefined","includePrerelease","versionAtLeast","minimum","isVersionUpgrade","incoming","existing","existingParsed","incomingParsed","catalogSupportCache","Map","resetCatalogSupportCache","clear","getLocalDependencySpecifier","packageManager","major","Number","parseInt","split","supportsCatalogs","cacheKey","cached","get","minimumVersion","supported","set","catalogsEnabled","config","catalogs","dependencies","devDependencies","packageJsonPath","callback","packageNames","Object","keys","convertDependenciesToCatalog","BUN_INTROSPECTED_PACKAGES","Set","isCatalogExcluded","packageName","has","catalogUpdates","json","field","includes","length","writeCatalogVersions","updates","applyUpdates","catalog","applicable","fromEntries","entries","filter","name","workspaceYaml","load","read","write","dump","quotingType","yarnRc"],"mappings":"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"}

package/src/utils/docker.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { type ProjectConfiguration, type Tree } from '@nx/devkit';
+import { type DependencyDeclaration, type MustDeclare } from './declared-dependencies';
+/** Dependencies a caller must declare to add a Docker scan target. */
+export declare const DOCKER_DEPENDENCIES: readonly [{
+    readonly name: "ncp";
+}, {
+    readonly name: "rimraf";
+}, {
+    readonly name: "make-dir-cli";
+}];
+/**
+ * Substitution variables for the vended Node `Dockerfile` templates: the npm
+ * version to install globally, and the versions its dependency overrides pin.
+ */
+export declare const nodeImageVersions: () => {
+    npmVersion: "12.0.2";
+    minimatchVersion: "10.2.6";
+};
+/**
+ * Packages a vended Node `Dockerfile` pins, which every generator writing one
+ * must declare so the version sync keeps those pins current.
+ *
+ * Spread through `ownedElsewhere`: the pin lives in the image build rather than
+ * in any manifest, so nothing is installed into the workspace. Left undeclared
+ * these would be the only vended versions never upgraded — and they are
+ * precisely the ones held at a version clear of a known HIGH/CRITICAL
+ * vulnerability.
+ */
+export declare const NODE_IMAGE_DEPENDENCIES: readonly [{
+    readonly name: "npm";
+}, {
+    readonly name: "minimatch";
+}];
+/**
+ * Packages the AWS Distro for OpenTelemetry install in a vended `Dockerfile`
+ * pins, for the images that auto-instrument with it. Spread through
+ * `ownedElsewhere` for the same reason as {@link NODE_IMAGE_DEPENDENCIES}.
+ */
+export declare const ADOT_IMAGE_DEPENDENCIES: readonly [{
+    readonly name: "@aws/aws-distro-opentelemetry-node-autoinstrumentation";
+}, {
+    readonly name: "@opentelemetry/propagator-jaeger";
+}];
+export interface DockerScanTargetOptions {
+    /**
+     * Project configuration to add the scan target to (mutated in place).
+     */
+    readonly project: ProjectConfiguration;
+    /**
+     * Container engine command to invoke (\`docker\` or \`finch\`).
+     */
+    readonly containerEngine: string;
+    /**
+     * Name of the scan target to add, e.g. \`my-agent-trivy\`.
+     */
+    readonly trivyTargetName: string;
+    /**
+     * Name of the docker target that builds the image(s) to scan. The scan
+     * target depends on it.
+     */
+    readonly dockerTargetName: string;
+    /**
+     * Tags of the images built by the docker target which should be scanned.
+     */
+    readonly imageTags: string[];
+}
+/**
+ * Add a cacheable Trivy scan target for the images built by a docker target
+ * and wire it under the aggregate \`trivy\` target. The scan is not part of
+ * \`build\` — run \`nx run-many --target trivy\` (the root \`trivy\` script) in CI.
+ *
+ * The scan target depends on the docker target and declares the project source
+ * as its inputs, so an unchanged image is never re-scanned (a cache hit skips
+ * the scan entirely). Each image is saved to a tarball under
+ * \`dist/<projectRoot>/trivy/<scan-key>\` (kept out of any Docker build context)
+ * and scanned with the pinned ECR-hosted Trivy image via a workspace-relative
+ * bind mount, so the same commands work under both docker and finch. The scan
+ * exits non-zero (exit code 1) on HIGH/CRITICAL vulnerabilities.
+ *
+ * A \`.trivyignore\` is vended at the project root (kept if it already exists)
+ * for suppressing findings.
+ */
+export declare const addDockerScanTarget: <const D extends DependencyDeclaration>(tree: Tree, options: DockerScanTargetOptions, declaration: D & MustDeclare<typeof DOCKER_DEPENDENCIES, D>) => void;