Issue: Allowed rule to force use of aliased-tsconfig import

[throrin19]

Expected Behavior

I try to create a rule to force the usage of aliased-tsconfig import instead of absolute impore (like use @company/module instead of libs/module.

I add this allowed rule :

{
    name     : 'absolute-libs',
    severity : 'error',
    comment  : 'on oblige l\'utilisation de `@module/` au lieu de `libs/`',
    from     : {},
    to       : {
        dependencyTypes : ['aliased-tsconfig'],
        path            : '^libs',
    },
},

Current Behavior

When I launch Depcruise, I have this unclear error :

The supplied configuration is not valid: data/allowed/0 must NOT have additional properties, data/allowed/0 must NOT have additional properties, data/allowed/0 must match exactly one schema in oneOf.

Possible Solution

Steps to Reproduce (for bugs)

1. Add the allowed rule in expected Behavior
2. Launch depcruise command
3. And voilà !

Context

Your Environment

• Version used: 15.1.1
• Node version: 18.18.2
• Operating System and version: MacOS 13.6
• Link to your project: Private project but I have explain my project in this issue : Question: How to use in monorepo project #859

[sverweij]

Hi @throrin19 thanks for asking, and sorry for the cryptic error message! It'd been more clear to have it say something like attribute 'severity' doesn't exist in statements within the 'allowed' rule, to specify the severity of the allowed rule, use allowedSeverity on the top level of your configuration. Also, individual statements within the allowed rule don't have their own 'name' attribute.

In general the allowed rule is trickier to set up than I anticipated when I introduced it a few years ago (more on why that is below). In stead it is often possible to add a rule to the forbiddenlist that expresses the same, but takes less effort. E.g. to ensure imports from ^libs are always done with a tsconfig alias one could write

// ...
{
  forbidden: [
    {
      "name": "imports-from-libs-with-aliases-only",
      // (French grammar police will be surrounding my house soon, probably, but ...)
      "comment": "importer depuis des /libs ? Utilisez un alias des tsconfig-paths (`@module/`) !", 
      "severity": "error",
      "from": {
      },
      "to": {
        "path": "^lib/",
        "dependencyTypesNot": ["aliased-tsconfig"]
      }
    },
  // ... other rules
  ],
// ...
}

To achieve something similar with the 'allowed' rule is more complicated as every statement in that rule should evaluate to true to pass. So this might look like a promising start:

{
  allowed: [
    {
      // (French grammar police will be surrounding my house soon, probably, but ...)
      "comment": "importer depuis des /libs ? Utilisez un alias des tsconfig-paths (`@module/`) !", 
      "from": {
      },
      "to": {
        "path": "^lib/",
        "dependencyTypes": ["aliased-tsconfig"]
      }
    },
  ],
  allowedSeverity: "error"
}

However this means that the only dependencies that are allowed are those that are aliased, and go to ^libs. This would exclude dependencies to core or npm modules. Or dependencies within the ^apps/ folder , ... So we need to have an extra statement to disclaim that.

{
  allowed: [
    {
      "from": {
      },
      "to": {
        "path": "^lib/",
        "dependencyTypes": ["aliased-tsconfig"]
      }
    },
    {
      "from": {
      },
      "to": {
        "pathNot": "^lib/",
      }
    }
  ],
  allowedSeverity: "error"
}

This can quickly spiral out of control. I.e. now it's not possible to have an import like import { lalala } from './aides' in /lib/livre/src/index.ts. So that'd need to be compensated as well ...

Anyway: thanks for this question!! It made me realize the documentation needs a clarification section. I hope the explanation above already helps a bit.

[throrin19]

Thank you for your feedback and explanations. I understand better the use of Allowed and indeed I had misunderstood its use.

[throrin19]

Sorry for the reopen. After test of this forbidden rule, I have a problem : All call inside one library are in error because I use relative path instead of alias (It's normal, we are inside the same library).

How to avoid this errors ?

For example, If I'm in libs/types, calls to files inside libs/types are not called with typescript alias. But if libs/types is called outside, we should use the typescript alias.

error not-relative-libs-import: libs/types/types/rights.d.ts → libs/types/types/helpers.d.ts
error not-relative-libs-import: libs/types/types/currentUser.d.ts → libs/types/types/rights.d.ts
error not-relative-libs-import: libs/types/index.d.ts → libs/types/types/rights.d.ts
error not-relative-libs-import: libs/types/index.d.ts → libs/types/types/helpers.d.ts
error not-relative-libs-import: libs/types/index.d.ts → libs/types/types/currentUser.d.ts
error not-relative-libs-import: libs/types/index.d.ts → libs/types/types/authToken.d.ts

In documentation I found we can link to with from regexp groups but not the other way around.

[sverweij]

Hi @throrin19 I should've included in my example yesterday. A way I use to solve this is to have two rules:

• one for modules outside libs
• one for modules inside them

so, like this:

// ...
{
  forbidden: [
    {
      "name": "imports-from-outside-libs-with-aliases-only",
      "severity": "error",
      "from": {
        "pathNot": "^lib/",
      },
      "to": {
        "path": "^lib/",
        "dependencyTypesNot": ["aliased-tsconfig"]
      }
    },
    {
      "name": "imports-from-other-libs-with-aliases-only",
      "severity": "error",
      "from": {
        "path": "(^lib/[^/]+/)", // if this matches e.g. lib/livres/src/quelquechose.ts ...
      },
      "to": {
        "path": "^lib/",
        "pathNot": "$1",        // ...then this matches lib/livres, ensuring the rule doesn't apply to lib/livres itself.
        "dependencyTypesNot": ["aliased-tsconfig"]
      }
    },
  // ... other rules
  ],
// ...
}

I'm using this setup in dependency-cruiser itself now as well to ensure
subpath-imports (the node.js native version of tsconfig paths that works
out of the box) are used wherever possible. Thanks for the inspiration!

[throrin19]

Thanks @sverweij but I have problems for specific checks

• Works fine :
  • If I import using relativePath it works fine, I have error import myLib from '../otherLib';
  • If I import using TS alias, it works fine, I have no error import myLib from '@company/otherLib;`
  • If I import content inside the library, it works fine, I have no error import otherFile from './otherFile';
• Wrong check :
  • If I import using workspace paths, I have no error import myLib from 'libs/otherLib';

[sverweij]

So import myLib from 'libs/otherLib' should be import myLib from '@company/otherLib' instead? From within the libs folder or outside it?

[throrin19]

If we want to call another lib, whether we're in the libs folder or not, I want to go through @company/libName.

[sverweij]

Hi @throrin19 you found a bug, thanks for letting me know! After some detective work it turned out that workspace paths in quite a few cases were erroneously classified as aliased-tsconfig. The PR above fixes this for the vast majority of cases. It's published as dependency-cruiser@15.3.0 just now.

Let me know if it indeed fixed the issue for you as well!

The only edge case where workspaces paths are now sometimes aren't detected as such is when
preserveSymlinks in .dependency-cruiser.js is switched to true and there's some
specific conditions with package names & locations that don't line up. As in the
.dependency-cruiser.js you shared earlier preserveSymlinks is left at the default (false)
it should work for you.

[throrin19]

Unfortunately, If I'm with this forbidden rules :

 {
            name        : 'imports-from-outside-libs-with-aliases-only',
            severity    : 'error',
            from        : {
                pathNot : '^libs/',
            },
            to : {
                path                : '^libs/',
                dependencyTypesNot  : ['aliased-tsconfig'],
            },
        },
        {
            name        : 'imports-from-other-libs-with-aliases-only',
            severity    : 'error',
            from        : {
                path : '(^libs/[^/]+/)', // if this matches e.g. lib/livres/src/quelquechose.ts ...
            },
            to : {
                path                : '^libs/',
                pathNot             : '$1',        // ...then this matches lib/livres, ensuring the rule doesn't apply to lib/livres itself.
                dependencyTypesNot  : ['aliased-tsconfig'],
            },
        },

I have exactly same result as before update dependency-cruiser. I try with preserveSymlinks true or false and I have the same result.

For Example I have 2 libraries and one stack :

├── libs
│   ├── configuration   # load outside with ts-alias `@company/configuration`
│   │    ├── index.ts   # entrypoint
│   │    ├── src
│   │    │   ├── config.ts
│   ├──  models         # load outside with ts-alias `@company/models`
│   │    ├── index.ts   # entrypoint
│   │    ├── src
│   │    │   ├──model.ts
├── stacks
│   ├──  users          # load outside with ts-alias `@company/users`
│   │    ├── index.ts   # entrypoint
│   │    ├── src
│   │    │   ├──handler.ts

If I wait to use libs/configuration inside libs/models or stacks/users I want to call it with @company/configuration, not with libs/configuration :

// outside libs/configuration
import { myConfig } from 'libs/configuration'; // BAD
import { myConfig } from '@company/configuration'; // GOOD

// inside libs/configuration/index.ts
export * from './src/config.ts'; // GOOD

[stelescuraul]

I believe I am running into a problem similar to above but only using the aliased-workspace dependency type.
I have made a git repo where you can see the issue: https://github.com/stelescuraul/dep-cruiser-issue
It is an npm workspace project, using package.json->name to reference modules.
Here's the structure of the project:

.
├── libs
│  ├── common
│  │  ├── index.js
│  │  └── package.json
│  └── math
│     ├── index.js
│     ├── package.json
│     └── src
│        └── foo.js
├── package-lock.json
├── package.json
├── projects
│  └── api
│     ├── main.js
│     ├── models.js
│     └── package.json

I would expect that libs can be imported from anywhere. Projects can import libs, and libs can import each other (this might be tighten in the future). For example math can import common. However, I expect all these imports to happen via the aliased defined by each lib in their own package.json and not via relative paths. Eg: import foo from '@foo/common'.

The dependencies are defined in a single package.json across all projects/libs, so only the root package.json will ever contain dependencies. Adding combinedDependencies works fine in this regard, however I can't seem to make the rules work without adding preserveSymlinks: true which in turn makes the graph look wrong. With preserveSymlinks the dependency graph will point to @foo/common inside node_modules instead of directly on the source under libs.
I would expect that when the dependencyType is set to aliased-workspace the rules would work without preserveSymlinks.

Here's an example of the ones that fail:

  error no-import-module-from-outside: libs/math/index.js → projects/api/models.js -> this is correct
  error imports-from-outside-libs-with-aliases-only: projects/api/main.js → libs/math/src/foo.js -> this should be fine
  error imports-from-outside-libs-with-aliases-only: projects/api/main.js → libs/math/index.js -> this should be fine
  error imports-from-other-libs-with-aliases-only: libs/math/src/foo.js → libs/common/index.js -> this should be fine

If I add preserveSymlinks it seems like the package cannot be resolved because they are not defined as direct dependency in the first found package.json (basically it looks like it ignores combinedDependencies option). The output is:

  error no-non-package-json: projects/api/main.js → node_modules/@foo/math/src/foo.js -> wrong
  error no-non-package-json: projects/api/main.js → node_modules/@foo/math/index.js -> wrong
  error no-non-package-json: libs/math/src/foo.js → node_modules/@foo/common/index.js -> wrong
  error no-import-module-from-outside: libs/math/index.js → projects/api/models.js -> correct

To get around this, I need to add couldNotResolve: true to the no-non-package-json rule. This might be expected behaviour but the graph should still figure out that the dependencies are in fact aliased and point to the ones directly under /lib.

Do you have an idea if this is wrong configuration on my side or is it a bug/feature request?

[sverweij]

Hi @throrin19 thanks for the feedback. Clearly there's still something that doesn't work like it should. To determine what exactly I need a minimal reproduction sample. Luckily @stelescuraul provided one (thanks!!!) and that helped to find the root cause. Next step is to write some extra tests & cook a fix.

Unexpectedly the root is in the mechanism to merge multiple package.json's - to save processing & memory that only merges those parts of package.json's that are relevant for dependency-cruiser (dependencies, devDependencies, bundledDependencies, ...) but nothing else. So the fix is to also process the workspaces field.

[sverweij]

@throrin19 @stelescuraul there's a quick fix (see above) which I've published as dependency-cruiser@15.3.1-beta-1. It seems to work as desired against the minimal repro repo:

$ npx depcruise projects libs

  error no-import-module-from-outside: libs/math/index.js → projects/api/models.js

✘ 1 dependency violations (1 errors, 0 warnings). 5 modules, 5 dependencies cruised.

or, graphically:

I'll make the fix a bit better & add some non-regression guarantees in the code base before publising it as dependency-cruiser@latest - but would love to hear feedback on this version already!

[throrin19]

Hello @sverweij Thanks for all your works.

The fix is a bit violent 😄. Now all my imports (with or without the use of tsconfig aliases) are seen in error.

A little clarification I hadn't included: I use aliases for the libs but the libs and stacks folders are in the NPM workspaces.

[stelescuraul]

Thanks for the update @sverweij. The graph and aliases are now resolved, but I encounter a small issue. With the beta branch you added, everything works fine But I can't forbid imports using the folder paths directly. For example, in api/main.js I would expect the following:

import { sum } from "@foo/math"; -> ✅ works fine
import { foo } from "../../libs/math/src/foo.js"; ❌  -> I would expect this would not work but it does pass
// import { foo } from "@foo/math/src/foo.js"; ✅  -> works fine

I have tried adding this rule as well but it still fails:

    {
      name: "imports-from-outside-libs-with-aliases-only-local-packages",
      severity: "error",
      from: {
        pathNot: "^libs/",
      },
      to: {
        path: "^libs/",
        dependencyTypes: ["local"],
      }
    }

In the 15.3.0 the above is not allowed and it is covered directly by the rule imports-from-outside-libs-with-aliases-only.

[sverweij]

Hi @stelescuraul thanks for testing the beta! You found a bug: in the beta ../../libs/math/src/foo.js classified as aliased-workspace (in addition to local. Obviously it shouldn't have done that. Fixed now (with unit tests to prevent regression).

[sverweij]

Hi @throrin19 thanks for testing as well! Could it be the paths in the tsconfig.json's are the same as those used for workspaces (i.e. the name attribute in the package.json's of the packages being called)?

[throrin19]

Hi @sverweij. Yes normally it's the same

workspaces in package.json :

{
"workspaces": [
    "stacks/*",
    "libs/*"
  ]
}

tsconfig alias :

{
    "paths": {
      "@company/configuration": [
        "libs/configuration/index.ts"
      ],
      "@company/errors": [
        "libs/errors/index.ts"
      ],
      "@company/helper-aws": [
        "libs/helper-aws/index.ts"
      ],
    }
}

[sverweij]

Hi @throrin19 and @stelescuraul - yesterday I've released dependency-cruiser@15.3.1-beta-2 which I'm reasonably confident solves both the issues you found in beta-1.

@throrin19 if the 'violence' of beta-1 persists in beta-2 I'll have to write some additional detection logic. Tests I've done so far indicate it's not necessary, but I'm a fallible human being so it's not unthinkable I missed a scenario. Let me know if this is indeed the case!

[throrin19]

Hi @sverweij I try to test this as soon as possible :)

[stelescuraul]

version dependency-cruiser@15.3.1-beta-2 seems to be working fine for my use case! Thank you for the fixes.

[sverweij]

Thanks for the feedback @stelescuraul!

@throrin19 - today I got time to write a thorough integration test and I can still reproduce the issue you have, even with the latest betas. So I'm going to try a different approach.

[sverweij]

Back from the tsconfig resolution rabbit-hole - there's a dependency-cruiser@16.0.0-beta-2 out that fixes the issue more thoroughly and has the automated non-regression tests to prove it (see #867 for details).

I'm curious to see whether this also holds up in your environment @throrin19 - if you have a bit of time to test it out I'd be grateful to hear your feedback!

[throrin19]

it changes nothing for me. If I import like this :

import { getConfiguration } from 'libs/configuration';

it return no error :(

[sverweij]

Hi @throrin19 hmmm does your tsconfig.json contain a baseUrl e.g. "baseUrl": "./"? In that case the TypeScript compiler, and every resolver following its specification will try to resolve non-local to that baseUrl before doing anything else. Although not tsconfig paths it's still a resolution that takes place via tsconfig. See https://www.typescriptlang.org/tsconfig#baseUrl for details.

In 16.0.0-beta-2 I've added a sub-distinction for these two tsconfig alias types:

• aliased-tsconfig-base-url - when it was resolved relative to the "baseUrl attribute in the tsconfig
• aliased-tsconfig-paths - when it occurs in the "paths" attribute in tsconfig

So if you want that specificity you can use it in your rules. Alternatively you could remove the "baseUrl" from the tsconfig, which is what the official TypeScript language reference seems to suggest.

minimal reproduction repo

In case the issue persists: I've set up a minimal reproduction sample in dependency-cruiser-repro-repo/863. It does seem to properly distinguish tsconfig paths from e.g. workspaces aliases, as well as show whether it's a baseUrl or a paths type of tsconfig. The repo is set up to easily include new test cases in this area - so if it doesn't cover your use case (i.e. the baseUrl turns out to be not the culprit) I'd love to see it!

I did have to correct a few of the bits of the .dependency-cruiser.js I included above for typos, though (lib -> libs for one), but from the samples you provided after you probably already did those corrections yourself.

[throrin19]

Hi @sverweij Yes, I have a baseUrl in my tsconfig. I try with aliased-tsconfig-paths and it works fine \o/

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs.