Add affected_by option for explicit project dependencies

Enables projects to declare dependencies on files outside their directory
structure, addressing common monorepo scenarios where projects depend
on shared resources that cannot be detected through mix dependencies.

Use cases include:
- Shared configuration files across multiple projects
- Documentation changes that affect project builds
- Cross-language dependencies (e.g., Rust NIFs depending on Rust crates)
- Build artifacts or generated files from other projects

The affected_by paths are resolved relative to each project's root,
support wildcard patterns for flexible matching, and properly propagate
affected status through the dependency graph to ensure all upstream
projects are correctly marked when their dependencies change.

Author: pnezis

workspace/lib/workspace.ex

@@ -44,12 +44,12 @@ defmodule Workspace do
   ```
   my_workspace
   ├── apps
-  │   ├── api         # an API app 
+  │   ├── api         # an API app
   │   └── ui          # the UI project
   ├── mix.exs         # this is the workspace root definition
   ├── .workspace.exs  # the workspace config
   └── packages        # various reusable packages under packages
-      ├── package_a 
+      ├── package_a
       ├── package_b
       └── package_c
   ```
@@ -91,7 +91,7 @@ defmodule Workspace do
   > an exception will be raised.
   >
   > For example the following workspace:
-  > 
+  >
   > ```
   > my_workspace
   > ├── apps
@@ -123,7 +123,7 @@ defmodule Workspace do
   each project with graph metadata.
 
   > #### Inspecting the graph {: .tip}
-  > 
+  >
   > You can use the `workspace.graph` command in order to see the
   > graph of the given `workspace`. For example:
   >
@@ -198,7 +198,7 @@ defmodule Workspace do
     * `:modified` - returns only the modified projects, e.g. projects for which
     the code has changed
     * `:affected` - returns all affected projects. Affected projects are the
-    modified ones plus the 
+    modified ones plus the
 
   `:modified` and `:affected` can be combined with the global filtering options.
 
@@ -213,7 +213,7 @@ defmodule Workspace do
   > should select a specific top level app when building the project. This will
   > ignore all other irrelevant apps.
   >   - When changing a specific set of projects, you should use `:modified` for
-  > formatting the code since everything else is not affected. 
+  > formatting the code since everything else is not affected.
   >   - Similarly for testing you should use the `:affected` filtering since a
   > change on a project may affect all parents.
   >   - It is advised to have generic CI pipelines on master/main branches that
@@ -258,7 +258,7 @@ defmodule Workspace do
   >   classDef affected fill:#FA6,color:#FFF;
   >   classDef modified fill:#F33,color:#FFF;
   > ```
-  > 
+  >
   > Modified projects are indicated with red colors, and affected projects are
   > highlighted with orange color.
   >
@@ -275,6 +275,55 @@ defmodule Workspace do
   > mix workspace.run -t test --affected
   > ```
 
+  ### Explicit dependencies
+
+  Sometimes you may want to specify explicit dependencies between projects and files
+  that cannot be deduced by the mix dependencies. For example you may have a Rust NIF
+  project which uses a Rust crate also present in your monorepo, or you may require
+  some `*.exs` files that are shared across the workspace.
+
+  In such cases you can use the `:affected_by` option in the project's workspace config
+  to explicitly define those dependencies. If any of the files defined there
+  is changed, then the project is considered affected.
+
+  When workspace status is updated, the system checks if any changed files match
+  the patterns defined in `affected_by`. If a match is found, the project is marked
+  as `:affected` and will be included in affected project lists.
+
+  > #### Path Resolution & Patterns {: .info}
+  >
+  > All paths in `:affected_by` are resolved relative to the **workspace's root directory**.
+  > This means you can reference files outside your project using relative paths like
+  > `../shared/config.ex` or `../../docs/README.md`.
+  >
+  > The `:affected_by` option supports several path patterns:
+  >
+  > - **Exact file paths**: `"../shared/config.ex"` - matches only this specific file
+  > - **Wildcard patterns**:
+  >   - `"../shared/*.ex"` - matches any `.ex` file in the `../shared/` directory
+  >   - `"../docs/**/*.md"` - matches any `.md` file in the `../docs/` directory including
+  > nested directories
+  > - **Directory paths**: `"../shared/"` - matches any file within the `../shared/` directory
+  >
+  > For example:
+  >
+  > ```elixir
+  > # In a project's mix.exs
+  > def project do
+  >   [
+  >     # ... other config
+  >     workspace: [
+  >       affected_by: [
+  >         "../shared/config.ex",           # Specific file
+  >         "../shared/*.ex",                # All .ex files in shared directory
+  >         "../../docs/**/*.md",             # All markdown files in docs including nested directories
+  >         "../shared/",                    # Any file in shared directory
+  >       ]
+  >     ]
+  >   ]
+  > end
+  > ```
+
   ## Environment variables
 
   The following environment variables are supported:
@@ -575,7 +624,7 @@ defmodule Workspace do
   end
 
   @doc """
-  Returns `true` if the given `app` is a `workspace` project, `false` otherwise. 
+  Returns `true` if the given `app` is a `workspace` project, `false` otherwise.
   """
   @spec project?(workspace :: Workspace.State.t(), app :: atom()) :: boolean()
   def project?(workspace, app) when is_struct(workspace, Workspace.State) and is_atom(app),

workspace/lib/workspace/project.ex

@@ -13,6 +13,25 @@ defmodule Workspace.Project do
       """,
       required: false,
       default: []
+    ],
+    affected_by: [
+      type: {:list, :string},
+      doc: """
+      List of file paths that if changed will mark this project as affected.
+      This is useful when a project depends on files outside of its root path.
+      Paths are relative to the project's root directory and support wildcards.
+
+      ```elixir
+      affected_by: ["../shared/config.ex", "../../docs/*.md", "config/*.json"]
+      ```
+
+      Supported wildcards:
+      - `*` matches any characters except path separators
+      - `?` matches a single character
+      - Directory paths will match any file within that directory
+      """,
+      required: false,
+      default: []
     ]
   ]
 
@@ -56,7 +75,8 @@ defmodule Workspace.Project do
           status: :undefined | :unaffected | :modified | :affected,
           root?: nil | boolean(),
           changes: nil | [{Path.t(), Workspace.Git.change_type()}],
-          tags: [tag()]
+          tags: [tag()],
+          affected_by: [String.t()]
         }
 
   @enforce_keys [:app, :module, :config, :mix_path, :path, :workspace_path]
@@ -70,7 +90,8 @@ defmodule Workspace.Project do
             status: :undefined,
             root?: nil,
             changes: nil,
-            tags: []
+            tags: [],
+            affected_by: []
 
   @doc """
   Creates a new project for the given project path.
@@ -109,15 +130,20 @@ defmodule Workspace.Project do
         ) :: t()
   def new(workspace_path, mix_path, module, config) do
     workspace_config = validate_workspace_project_config!(config)
+    project_path = Path.dirname(mix_path)
+
+    # Expand affected_by paths relative to the project path
+    affected_by = Enum.map(workspace_config[:affected_by], &Path.expand(&1, project_path))
 
     %__MODULE__{
       app: config[:app],
       module: module,
       config: config,
       mix_path: mix_path,
-      path: Path.dirname(mix_path),
+      path: project_path,
       workspace_path: workspace_path,
-      tags: workspace_config[:tags]
+      tags: workspace_config[:tags],
+      affected_by: affected_by
     }
   end
 

workspace/lib/workspace/status.ex

@@ -54,9 +54,16 @@ defmodule Workspace.Status do
             end)
           end)
 
-        # Affected projects
+        # Check for projects affected by their affected_by paths
+        affected_by_changes = check_affected_by_paths(workspace, changes)
+
+        # Affected projects (from dependencies + affected_by paths)
         modified = Enum.map(modifications, fn {project, _changes} -> project end)
-        affected = Workspace.Graph.affected(workspace, modified)
+
+        affected_by_modified =
+          Enum.map(affected_by_changes, fn {project, _changes} -> project end)
+
+        affected = Workspace.Graph.affected(workspace, modified ++ affected_by_modified)
 
         projects =
           Enum.reduce(affected, projects, fn project, workspace_projects ->
@@ -167,4 +174,48 @@ defmodule Workspace.Status do
     |> Enum.map(fn {name, _project} -> name end)
     |> Enum.sort()
   end
+
+  defp check_affected_by_paths(workspace, changes) do
+    base_path = workspace.git_root_path || workspace.workspace_path
+
+    # Expand all changed files to full paths
+    changed_files =
+      changes
+      |> Map.values()
+      |> List.flatten()
+      |> Enum.map(fn {changed_file, type} ->
+        {Path.expand(changed_file, base_path), type}
+      end)
+
+    # Check each project's affected_by paths
+    workspace.projects
+    |> Enum.filter(fn {_name, project} -> length(project.affected_by) > 0 end)
+    |> Enum.reduce(%{}, fn {name, project}, acc ->
+      affected_files =
+        project.affected_by
+        |> Enum.filter(fn affected_path ->
+          # affected_path is already expanded in project creation
+          # Check if any changed file matches this affected_by path
+          Enum.any?(changed_files, fn {full_changed_path, _type} ->
+            matches_affected_by_path?(full_changed_path, affected_path)
+          end)
+        end)
+
+      if length(affected_files) > 0 do
+        # Create file_info entries for the affected files
+        file_infos = Enum.map(affected_files, fn file -> {file, :modified} end)
+        Map.put(acc, name, file_infos)
+      else
+        acc
+      end
+    end)
+  end
+
+  defp matches_affected_by_path?(changed_path, affected_path) do
+    cond do
+      Workspace.Utils.Path.parent_dir?(affected_path, changed_path) -> true
+      changed_path in Path.wildcard(affected_path) -> true
+      true -> false
+    end
+  end
 end

workspace/test/workspace/status_test.exs

@@ -237,15 +237,15 @@ defmodule Workspace.StatusTest do
 
         Workspace.Test.commit_changes(tmp_dir)
 
-        # modify both workspaces 
+        # modify both workspaces
         Workspace.Test.modify_project(workspace_path, "packages/foo")
         Workspace.Test.modify_project(another_workspace_path, "packages/bar")
 
         workspace = Workspace.new!(workspace_path)
         another_workspace = Workspace.new!(another_workspace_path)
 
         # the changed files should include the changed project, with paths relative to
-        # the git root, the changed file of the other workspace should be under `nil` 
+        # the git root, the changed file of the other workspace should be under `nil`
         assert Workspace.Status.changed(workspace) == %{
                  nil: [{"nested/another_workspace/packages/bar/lib/file.ex", :untracked}],
                  foo: [{"workspace/packages/foo/lib/file.ex", :untracked}]
@@ -265,4 +265,110 @@ defmodule Workspace.StatusTest do
       end)
     end
   end
+
+  describe "affected_by paths" do
+    @tag :tmp_dir
+    test "marks project as affected when affected_by files change", %{tmp_dir: tmp_dir} do
+      Workspace.Test.with_workspace(
+        tmp_dir,
+        [],
+        [
+          {:package_a, "package_a", [workspace: [affected_by: ["../shared/config.ex"]]]},
+          {:package_b, "package_b", [workspace: [affected_by: ["../docs/*.md"]]]}
+        ],
+        fn ->
+          # Create shared files
+          shared_dir = Path.join(tmp_dir, "shared")
+          File.mkdir_p!(shared_dir)
+          File.write!(Path.join(shared_dir, "config.ex"), "# config")
+
+          workspace = Workspace.new!(tmp_dir)
+          refute workspace.status_updated?
+
+          # Modify shared config file
+          File.write!(Path.join(shared_dir, "config.ex"), "# updated config")
+
+          workspace = Workspace.Status.update(workspace, [])
+          assert workspace.status_updated?
+
+          # package_a should be affected due to shared/config.ex change
+          assert workspace.projects[:package_a].status == :affected
+          # package_b should be unaffected
+          assert workspace.projects[:package_b].status == :undefined
+
+          docs_dir = Path.join(tmp_dir, "docs")
+          File.mkdir_p!(docs_dir)
+          File.write!(Path.join(docs_dir, "README.md"), "# docs")
+
+          workspace = Workspace.Status.update(workspace, force: true)
+          assert workspace.status_updated?
+
+          # package_b should be affected due to docs/*.md change
+          assert workspace.projects[:package_b].status == :affected
+        end,
+        git: true
+      )
+    end
+
+    @tag :tmp_dir
+    test "supports wildcard patterns in affected_by", %{tmp_dir: tmp_dir} do
+      Workspace.Test.with_workspace(
+        tmp_dir,
+        [],
+        [
+          {:package_a, "package_a", [workspace: [affected_by: ["../shared/*.ex"]]]}
+        ],
+        fn ->
+          # Create shared files
+          shared_dir = Path.join(tmp_dir, "shared")
+          File.mkdir_p!(shared_dir)
+
+          File.write!(Path.join(shared_dir, "config.txt"), "# config")
+
+          workspace = Workspace.new!(tmp_dir)
+          refute workspace.status_updated?
+
+          # should not be affected by a *.txt change
+          assert workspace.projects[:package_a].status == :undefined
+
+          # Modify .ex file in shared (should match)
+          File.write!(Path.join(shared_dir, "utils.ex"), "# updated utils")
+
+          workspace = Workspace.Status.update(workspace, force: true)
+          assert workspace.status_updated?
+
+          # package_a should be affected
+          assert workspace.projects[:package_a].status == :affected
+        end,
+        git: true
+      )
+    end
+  end
+
+  @tag :tmp_dir
+  test "supports parent directory in affected_by", %{tmp_dir: tmp_dir} do
+    Workspace.Test.with_workspace(
+      tmp_dir,
+      [],
+      [
+        {:package_a, "package_a", [workspace: [affected_by: ["../shared"]]]}
+      ],
+      fn ->
+        workspace = Workspace.new!(tmp_dir)
+        workspace = Workspace.Status.update(workspace, force: true)
+
+        assert workspace.projects[:package_a].status == :undefined
+
+        # Create shared files
+        shared_dir = Path.join(tmp_dir, "shared")
+        File.mkdir_p!(shared_dir)
+
+        File.write!(Path.join(shared_dir, "config.txt"), "# config")
+
+        workspace = Workspace.Status.update(workspace, force: true)
+        assert workspace.projects[:package_a].status == :affected
+      end,
+      git: true
+    )
+  end
 end