feat: adds 'ancestor' matcher

[sverweij]

Description

• adds an ancestor matcher

Motivation and Context

It's probably possible to do this with regular expressions and group matching, but so far I haven't found a simple way to do that.

How Has This Been Tested?

• green ci
• additional automated integration tests
• additional automated unit tests
• self-run (added a no-ancestors rule to our own .dependency-cruiser.mjs)

Screenshots

You can now do things like this:

// in the `forbidden` section of a dependency-cruiser config:
{
  name: "no-ancestor",
  comment: "don't allow importing from folders above the current one",
  severity: "error",
  from: {},
  to: { "ancestor": true }
}

Which, when run as part of a validation, would yield errors on every dependency that goes folders up in stead of down:

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• Documentation only change
• Refactor (non-breaking change which fixes an issue without changing functionality)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist

• 📖

  • My change doesn't require a documentation update, or ...
  • it does and I have updated it

• ⚖️

  • The contribution will be subject to The MIT license, and I'm OK with that.
  • The contribution is my own original work.
  • I am ok with the stuff in CONTRIBUTING.md.

[Copilot]

Pull Request Overview

This pull request adds a new "ancestor" matcher that allows users to flag dependencies where the target module is located in a folder above the source module. The changes include updates to type definitions and schemas, new matcher logic in the validation code, comprehensive tests, and corresponding documentation.

Reviewed Changes

Copilot reviewed 12 out of 15 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
types/restrictions.d.mts	Added the optional "ancestor" property to the to-restrictions.
tools/schema/restrictions.mjs	Updated the restrictions schema with the "ancestor" property.
test/validate/matchers.spec.mjs	Added tests for the ancestor matcher behavior.
test/validate/index.ancestor.spec.mjs	Added integration tests for dependencies using the ancestor rule.
src/validate/matchers.mjs	Implemented the new matchesAncestor() function and renamed helpers.
src/validate/match-dependency-rule.mjs	Integrated matchesAncestor into the dependency rule matching.
src/schema/cruise-result.schema.mjs	Updated output schema to incorporate the "ancestor" property.
src/schema/configuration.schema.mjs	Updated configuration schema with the new ancestor restriction.
doc/rules-reference.md	Documented the new ancestor rule.
.dependency-cruiser.mjs	Added sample rules utilizing the ancestor matcher.

Files not reviewed (3)

• .dependency-cruiser-known-violations.json: Language not supported
• src/schema/configuration.schema.json: Language not supported
• src/schema/cruise-result.schema.json: Language not supported

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud