feat(core): add api for v2 of project project graph plugins

[AgentEnder]

Current Behavior

There are 2 methods to interact with the project graph:

• Project Inference
  • registerProjectTargets
  • projectFilePatterns
• Project graph plugins
  • processProjectGraph

These 2 methods create some pain for us as we try to work on the internal code base, and there are some issues with the current inference APIs.

• Current API requires 1:1 association between project files and projects. This doesn't work for cases like:
  • angular.json
  • someCsProject.sln
  • gradle files
• processProjectGraph allows adding nodes to the graph, which seems like it would work as a project inference method outside of the official inference APIs. Adding nodes like this results in the project file map not being correctly calculated though, since they are added after we calculate the map.
• We can't really optimize things for knowing when dependencies and nodes are added, since they are potentially done in parallel rather than ensuring all nodes are present first.

Expected Behavior

Plugins have 2 APIs for updating the graph:

• createNodes
• createDependencies

This allows us to proceed while knowing that the graph is updated with all nodes, and afterwards we can create dependencies between them.

CreateNodes

Provides a glob pattern and factory to construct nodes from files that match that pattern. As an example, consider the implementation of the project.json node creator:

const PROJECT_JSON_PLUGIN = {
    name: 'nx-core-build-project-json-nodes',
    createNodes: [
      '{project.json,**/project.json}',
      (file) => {
        const json = readJsonFile<ProjectConfiguration>(join(root, file));
        const project = buildProjectFromProjectJson(json, file);
        return {
          projects: {
            [project.name]: project,
          },
        };
      },
    ],
  };

The createNodes property is a tuple. The first element is the glob pattern, which says that we want all project.json files, including the one at the root if it is present. The second element is a function that takes the path to an individual file that was identified as matching the provided glob pattern, and returns all projects and external dependencies which are read from that file.

In the case of project.json this is a single project. A similar plugin to support workspace.json would look like this:

WARNING
This plugin isn't included, since we don't support workspace.json any more. It is strictly an example.

const WORKSPACE_JSON_PLUGIN = {
    name: 'nx-core-build-workspace-json-nodes',
    createNodes: [
      'workspace.json',
      (file) => {
        const json = readJsonFile(file);
        return {
          projects: json.projects
        };
      },
    ],
  };

CreateDependencies

createDependencies returns an array of dependencies which should be added to the graph. It receives as arguments a context argument similar to the context currently provided to processProjectGraph

Known Limitations

The new APIs don't include methods to remove nodes or dependencies. We can't really find a valid use case for doing so, and it would result in complicating the return types of each of the methods.

Related Issue(s)

Fixes #

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
nx-dev	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Aug 10, 2023 5:27pm

[nx-cloud]

☁️ Nx Cloud Report

CI is running/has finished running commands for commit 1885132. As they complete they will appear below. Click to see the status, the terminal output, and the build insights.

📂 See all runs for this branch

---

✅ Successfully ran 8 targets

• linux nx affected --target=e2e --base=e52b1d095a268daaa3b0959f8d4d6327c7afde39 --head=18851326b4faef621ca2febaa2739ff800902518 --parallel=1
• linux nx affected --target=build --base=e52b1d095a268daaa3b0959f8d4d6327c7afde39 --head=18851326b4faef621ca2febaa2739ff800902518 --parallel=3
• linux nx run-many -t check-imports check-commit check-lock-files check-codeowners documentation --parallel=1 --no-dte
• linux nx affected --target=lint --base=e52b1d095a268daaa3b0959f8d4d6327c7afde39 --head=18851326b4faef621ca2febaa2739ff800902518 --parallel=3
• linux nx affected --target=test --base=e52b1d095a268daaa3b0959f8d4d6327c7afde39 --head=18851326b4faef621ca2febaa2739ff800902518 --parallel=1
• nx-cloud record -- nx format:check --base=e52b1d095a268daaa3b0959f8d4d6327c7afde39 --head=18851326b4faef621ca2febaa2739ff800902518
• linux nx documentation --no-dte
• macos nx affected -t e2e-macos --parallel=1 --base=e52b1d095a268daaa3b0959f8d4d6327c7afde39 --head=18851326b4faef621ca2febaa2739ff800902518

---

Sent with 💌 from NxCloud.

[github-actions]

This pull request has already been merged/closed. If you experience issues related to these changes, please open a new issue referencing this pull request.