cleanup(core): adjust create dependencies context (#19070)

Co-authored-by: FrozenPandaz <[email protected]>

docs/generated/devkit/CreateDependencies.md

@@ -1,10 +1,10 @@
 # Type alias: CreateDependencies
 
-Ƭ **CreateDependencies**: (`context`: [`CreateDependenciesContext`](../../devkit/documents/CreateDependenciesContext)) => [`ProjectGraphDependencyWithFile`](../../devkit/documents/ProjectGraphDependencyWithFile)[] \| `Promise`<[`ProjectGraphDependencyWithFile`](../../devkit/documents/ProjectGraphDependencyWithFile)[]\>
+Ƭ **CreateDependencies**: (`context`: [`CreateDependenciesContext`](../../devkit/documents/CreateDependenciesContext)) => [`RawProjectGraphDependency`](../../devkit/documents/RawProjectGraphDependency)[] \| `Promise`<[`RawProjectGraphDependency`](../../devkit/documents/RawProjectGraphDependency)[]\>
 
 #### Type declaration
 
-▸ (`context`): [`ProjectGraphDependencyWithFile`](../../devkit/documents/ProjectGraphDependencyWithFile)[] \| `Promise`<[`ProjectGraphDependencyWithFile`](../../devkit/documents/ProjectGraphDependencyWithFile)[]\>
+▸ (`context`): [`RawProjectGraphDependency`](../../devkit/documents/RawProjectGraphDependency)[] \| `Promise`<[`RawProjectGraphDependency`](../../devkit/documents/RawProjectGraphDependency)[]\>
 
 A function which parses files in the workspace to create dependencies in the [ProjectGraph](../../devkit/documents/ProjectGraph)
 Use [validateDependency](../../devkit/documents/validateDependency) to validate dependencies
@@ -17,4 +17,4 @@ Use [validateDependency](../../devkit/documents/validateDependency) to validate
 
 ##### Returns
 
-[`ProjectGraphDependencyWithFile`](../../devkit/documents/ProjectGraphDependencyWithFile)[] \| `Promise`<[`ProjectGraphDependencyWithFile`](../../devkit/documents/ProjectGraphDependencyWithFile)[]\>
+[`RawProjectGraphDependency`](../../devkit/documents/RawProjectGraphDependency)[] \| `Promise`<[`RawProjectGraphDependency`](../../devkit/documents/RawProjectGraphDependency)[]\>

docs/generated/devkit/CreateDependenciesContext.md

@@ -6,14 +6,23 @@ Context for [CreateDependencies](../../devkit/documents/CreateDependencies)
 
 ### Properties
 
+- [externalNodes](../../devkit/documents/CreateDependenciesContext#externalnodes): Record<string, ProjectGraphExternalNode>
 - [fileMap](../../devkit/documents/CreateDependenciesContext#filemap): ProjectFileMap
 - [filesToProcess](../../devkit/documents/CreateDependenciesContext#filestoprocess): ProjectFileMap
-- [graph](../../devkit/documents/CreateDependenciesContext#graph): ProjectGraph
 - [nxJsonConfiguration](../../devkit/documents/CreateDependenciesContext#nxjsonconfiguration): NxJsonConfiguration<string[] | "\*">
-- [projectsConfigurations](../../devkit/documents/CreateDependenciesContext#projectsconfigurations): ProjectsConfigurations
+- [projects](../../devkit/documents/CreateDependenciesContext#projects): Record<string, ProjectConfiguration>
+- [workspaceRoot](../../devkit/documents/CreateDependenciesContext#workspaceroot): string
 
 ## Properties
 
+### externalNodes
+
+• `Readonly` **externalNodes**: `Record`<`string`, [`ProjectGraphExternalNode`](../../devkit/documents/ProjectGraphExternalNode)\>
+
+The external nodes that have been added to the graph.
+
+---
+
 ### fileMap
 
 • `Readonly` **fileMap**: [`ProjectFileMap`](../../devkit/documents/ProjectFileMap)
@@ -30,24 +39,22 @@ Files changes since last invocation
 
 ---
 
-### graph
+### nxJsonConfiguration
 
-• `Readonly` **graph**: [`ProjectGraph`](../../devkit/documents/ProjectGraph)
+• `Readonly` **nxJsonConfiguration**: [`NxJsonConfiguration`](../../devkit/documents/NxJsonConfiguration)<`string`[] \| `"*"`\>
 
-The current project graph,
+The `nx.json` configuration from the workspace
 
 ---
 
-### nxJsonConfiguration
+### projects
 
-• `Readonly` **nxJsonConfiguration**: [`NxJsonConfiguration`](../../devkit/documents/NxJsonConfiguration)<`string`[] \| `"*"`\>
+• `Readonly` **projects**: `Record`<`string`, [`ProjectConfiguration`](../../devkit/documents/ProjectConfiguration)\>
 
-The `nx.json` configuration from the workspace
+The configuration of each project in the workspace.
 
 ---
 
-### projectsConfigurations
-
-• `Readonly` **projectsConfigurations**: [`ProjectsConfigurations`](../../devkit/documents/ProjectsConfigurations)
+### workspaceRoot
 
-The configuration of each project in the workspace
+• `Readonly` **workspaceRoot**: `string`

docs/generated/devkit/DynamicDependency.md

@@ -0,0 +1,16 @@
+# Type alias: DynamicDependency
+
+Ƭ **DynamicDependency**: `Object`
+
+A dynamic [ProjectGraph](../../devkit/documents/ProjectGraph) dependency between 2 projects
+
+This type of dependency indicates the source project MAY OR MAY NOT load the target project.
+
+#### Type declaration
+
+| Name         | Type                                                              | Description                                                                                                                |
+| :----------- | :---------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------- |
+| `source`     | `string`                                                          | The name of a [ProjectGraphProjectNode](../../devkit/documents/ProjectGraphProjectNode) depending on the target project    |
+| `sourceFile` | `string`                                                          | The path of a file (relative from the workspace root) where the dependency is made                                         |
+| `target`     | `string`                                                          | The name of a [ProjectGraphProjectNode](../../devkit/documents/ProjectGraphProjectNode) that the source project depends on |
+| `type`       | typeof [`dynamic`](../../devkit/documents/DependencyType#dynamic) | -                                                                                                                          |

docs/generated/devkit/ImplicitDependency.md

@@ -0,0 +1,15 @@
+# Type alias: ImplicitDependency
+
+Ƭ **ImplicitDependency**: `Object`
+
+An implicit [ProjectGraph](../../devkit/documents/ProjectGraph) dependency between 2 projects
+
+This type of dependency indicates a connection without an explicit reference in code
+
+#### Type declaration
+
+| Name     | Type                                                                | Description                                                                                                                |
+| :------- | :------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------- |
+| `source` | `string`                                                            | The name of a [ProjectGraphProjectNode](../../devkit/documents/ProjectGraphProjectNode) depending on the target project    |
+| `target` | `string`                                                            | The name of a [ProjectGraphProjectNode](../../devkit/documents/ProjectGraphProjectNode) that the source project depends on |
+| `type`   | typeof [`implicit`](../../devkit/documents/DependencyType#implicit) | -                                                                                                                          |

docs/generated/devkit/README.md

@@ -43,7 +43,6 @@ It only uses language primitives and immutable objects
 - [ProjectFileMap](../../devkit/documents/ProjectFileMap)
 - [ProjectGraph](../../devkit/documents/ProjectGraph)
 - [ProjectGraphDependency](../../devkit/documents/ProjectGraphDependency)
-- [ProjectGraphDependencyWithFile](../../devkit/documents/ProjectGraphDependencyWithFile)
 - [ProjectGraphExternalNode](../../devkit/documents/ProjectGraphExternalNode)
 - [ProjectGraphProcessorContext](../../devkit/documents/ProjectGraphProcessorContext)
 - [ProjectGraphProjectNode](../../devkit/documents/ProjectGraphProjectNode)
@@ -66,10 +65,12 @@ It only uses language primitives and immutable objects
 - [CreateNodes](../../devkit/documents/CreateNodes)
 - [CreateNodesFunction](../../devkit/documents/CreateNodesFunction)
 - [CustomHasher](../../devkit/documents/CustomHasher)
+- [DynamicDependency](../../devkit/documents/DynamicDependency)
 - [Executor](../../devkit/documents/Executor)
 - [Generator](../../devkit/documents/Generator)
 - [GeneratorCallback](../../devkit/documents/GeneratorCallback)
 - [Hasher](../../devkit/documents/Hasher)
+- [ImplicitDependency](../../devkit/documents/ImplicitDependency)
 - [ImplicitDependencyEntry](../../devkit/documents/ImplicitDependencyEntry)
 - [NxPlugin](../../devkit/documents/NxPlugin)
 - [NxPluginV1](../../devkit/documents/NxPluginV1)
@@ -78,6 +79,8 @@ It only uses language primitives and immutable objects
 - [ProjectGraphNode](../../devkit/documents/ProjectGraphNode)
 - [ProjectTargetConfigurator](../../devkit/documents/ProjectTargetConfigurator)
 - [ProjectType](../../devkit/documents/ProjectType)
+- [RawProjectGraphDependency](../../devkit/documents/RawProjectGraphDependency)
+- [StaticDependency](../../devkit/documents/StaticDependency)
 - [StringChange](../../devkit/documents/StringChange)
 - [TaskGraphExecutor](../../devkit/documents/TaskGraphExecutor)
 - [WorkspaceConfiguration](../../devkit/documents/WorkspaceConfiguration)

docs/generated/devkit/RawProjectGraphDependency.md

@@ -0,0 +1,7 @@
+# Type alias: RawProjectGraphDependency
+
+Ƭ **RawProjectGraphDependency**: [`ImplicitDependency`](../../devkit/documents/ImplicitDependency) \| [`StaticDependency`](../../devkit/documents/StaticDependency) \| [`DynamicDependency`](../../devkit/documents/DynamicDependency)
+
+A [ProjectGraph](../../devkit/documents/ProjectGraph) dependency between 2 projects
+
+See [DynamicDependency](../../devkit/documents/DynamicDependency), [ImplicitDependency](../../devkit/documents/ImplicitDependency), or [StaticDependency](../../devkit/documents/StaticDependency)

docs/generated/devkit/StaticDependency.md

@@ -0,0 +1,18 @@
+# Type alias: StaticDependency
+
+Ƭ **StaticDependency**: `Object`
+
+A static [ProjectGraph](../../devkit/documents/ProjectGraph) dependency between 2 projects
+
+This type of dependency indicates the source project ALWAYS load the target project.
+
+NOTE: StaticDependency#sourceFile MUST be present unless the source is the name of a [ProjectGraphExternalNode](../../devkit/documents/ProjectGraphExternalNode)
+
+#### Type declaration
+
+| Name          | Type                                                            | Description                                                                                                                                                                                               |
+| :------------ | :-------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `source`      | `string`                                                        | The name of a [ProjectGraphProjectNode](../../devkit/documents/ProjectGraphProjectNode) or [ProjectGraphExternalNode](../../devkit/documents/ProjectGraphExternalNode) depending on the target project    |
+| `sourceFile?` | `string`                                                        | The path of a file (relative from the workspace root) where the dependency is made                                                                                                                        |
+| `target`      | `string`                                                        | The name of a [ProjectGraphProjectNode](../../devkit/documents/ProjectGraphProjectNode) or [ProjectGraphExternalNode](../../devkit/documents/ProjectGraphExternalNode) that the source project depends on |
+| `type`        | typeof [`static`](../../devkit/documents/DependencyType#static) | -                                                                                                                                                                                                         |

docs/generated/devkit/validateDependency.md

@@ -1,6 +1,6 @@
 # Function: validateDependency
 
-▸ **validateDependency**(`graph`, `dependency`): `void`
+▸ **validateDependency**(`dependency`, `ctx`): `void`
 
 A function to validate dependencies in a [CreateDependencies](../../devkit/documents/CreateDependencies) function
 
@@ -10,10 +10,10 @@ If the dependency is invalid.
 
 #### Parameters
 
-| Name         | Type                                                                                      |
-| :----------- | :---------------------------------------------------------------------------------------- |
-| `graph`      | [`ProjectGraph`](../../devkit/documents/ProjectGraph)                                     |
-| `dependency` | [`ProjectGraphDependencyWithFile`](../../devkit/documents/ProjectGraphDependencyWithFile) |
+| Name         | Type                                                                            |
+| :----------- | :------------------------------------------------------------------------------ |
+| `dependency` | [`RawProjectGraphDependency`](../../devkit/documents/RawProjectGraphDependency) |
+| `ctx`        | [`CreateDependenciesContext`](../../devkit/documents/CreateDependenciesContext) |
 
 #### Returns
 

docs/generated/packages/devkit/documents/nx_devkit.md

@@ -43,7 +43,6 @@ It only uses language primitives and immutable objects
 - [ProjectFileMap](../../devkit/documents/ProjectFileMap)
 - [ProjectGraph](../../devkit/documents/ProjectGraph)
 - [ProjectGraphDependency](../../devkit/documents/ProjectGraphDependency)
-- [ProjectGraphDependencyWithFile](../../devkit/documents/ProjectGraphDependencyWithFile)
 - [ProjectGraphExternalNode](../../devkit/documents/ProjectGraphExternalNode)
 - [ProjectGraphProcessorContext](../../devkit/documents/ProjectGraphProcessorContext)
 - [ProjectGraphProjectNode](../../devkit/documents/ProjectGraphProjectNode)
@@ -66,10 +65,12 @@ It only uses language primitives and immutable objects
 - [CreateNodes](../../devkit/documents/CreateNodes)
 - [CreateNodesFunction](../../devkit/documents/CreateNodesFunction)
 - [CustomHasher](../../devkit/documents/CustomHasher)
+- [DynamicDependency](../../devkit/documents/DynamicDependency)
 - [Executor](../../devkit/documents/Executor)
 - [Generator](../../devkit/documents/Generator)
 - [GeneratorCallback](../../devkit/documents/GeneratorCallback)
 - [Hasher](../../devkit/documents/Hasher)
+- [ImplicitDependency](../../devkit/documents/ImplicitDependency)
 - [ImplicitDependencyEntry](../../devkit/documents/ImplicitDependencyEntry)
 - [NxPlugin](../../devkit/documents/NxPlugin)
 - [NxPluginV1](../../devkit/documents/NxPluginV1)
@@ -78,6 +79,8 @@ It only uses language primitives and immutable objects
 - [ProjectGraphNode](../../devkit/documents/ProjectGraphNode)
 - [ProjectTargetConfigurator](../../devkit/documents/ProjectTargetConfigurator)
 - [ProjectType](../../devkit/documents/ProjectType)
+- [RawProjectGraphDependency](../../devkit/documents/RawProjectGraphDependency)
+- [StaticDependency](../../devkit/documents/StaticDependency)
 - [StringChange](../../devkit/documents/StringChange)
 - [TaskGraphExecutor](../../devkit/documents/TaskGraphExecutor)
 - [WorkspaceConfiguration](../../devkit/documents/WorkspaceConfiguration)

docs/shared/recipes/plugins/project-graph-plugins.md

@@ -90,16 +90,14 @@ The shape of the [`createDependencies`](/packages/devkit/documents/CreateDepende
 ```typescript
 export type CreateDependencies = (
   context: CreateDependenciesContext
-) =>
-  | ProjectGraphDependencyWithFile[]
-  | Promise<ProjectGraphDependencyWithFile[]>;
+) => CandidateDependency[] | Promise<CandidateDependency[]>;
 ```
 
 In the `createDependencies` function, you can analyze the files in the workspace and return a list of dependencies. It's up to the plugin to determine how to analyze the files. This should also be exported from the plugin's entry point, as listed in `nx.json`.
 
-Within the `CreateDependenciesContext`, you have access to the current project graph, the configuration of each project in the workspace, the `nx.json` configuration from the workspace, all files in the workspace, and files that have changed since the last invocation. It's important to utilize the `filesToProcess` parameter, as this will allow Nx to only reanalyze files that have changed since the last invocation, and reuse the information from the previous invocation for files that haven't changed.
+Within the `CreateDependenciesContext`, you have access to the graph's external nodes, the configuration of each project in the workspace, the `nx.json` configuration from the workspace, all files in the workspace, and files that have changed since the last invocation. It's important to utilize the `filesToProcess` parameter, as this will allow Nx to only reanalyze files that have changed since the last invocation, and reuse the information from the previous invocation for files that haven't changed.
 
-`@nx/devkit` exports a function called `validateDependency` which can be used to validate a dependency. This function takes in a `ProjectGraphDependencyWithFile` and a `ProjectGraph` and throws an error if the dependency is invalid. This function is called when the returned dependencies are merged with the existing project graph, but may be useful to call within your plugin to validate dependencies before returning them when debugging.
+`@nx/devkit` exports a function called `validateDependency` which can be used to validate a dependency. This function takes in a `CandidateDependency` and the `CreateDependenciesContext` and throws an error if the dependency is invalid. This function is called when the returned dependencies are merged with the existing project graph, but may be useful to call within your plugin to validate dependencies before returning them when debugging.
 
 The dependencies can be of three types:
 
@@ -184,7 +182,7 @@ export const createNodes: CreateNodes = (ctx) => {
             dependencyType: DependencyType.static,
           };
         }
-        validateDependency(ctx.graph, newDependency);
+        validateDependency(newDependency, ctx);
         results.push(newDependency);
       }
     }

packages/nx/src/devkit-exports.ts

@@ -156,7 +156,10 @@ export { DependencyType } from './config/project-graph';
  */
 export {
   ProjectGraphBuilder,
-  ProjectGraphDependencyWithFile,
+  RawProjectGraphDependency,
+  DynamicDependency,
+  ImplicitDependency,
+  StaticDependency,
   validateDependency,
 } from './project-graph/project-graph-builder';