Merge pull request #741 from protofire/fix-allow-scoped-packages

fix: scoped packs for shareable configs

Author: dbale-altoros

.github/workflows/E2E.yml

@@ -40,6 +40,11 @@ jobs:
 
       - name: Check solhint version
         run: solhint --version
+
+      - name: Debug fixtures presence
+        run: |
+          ls -R e2e/14-shareable-config/filesystem01/project || true
+          ls -R e2e/14-shareable-config/filesystem04/project || true  
       
       - name: Run E2E Tests
         run: npm run ci:e2e

.gitignore

@@ -1,4 +1,6 @@
+# ignore all node_modules by default
 node_modules/
+
 /.idea/
 test2.sol
 convertLib.sol
@@ -12,3 +14,9 @@ _temp/
 .env
 **/.DS_Store
 solhint*.tgz
+
+# Exception on E2E fixtures' node_modules (they are part of the test data)
+# only allow .js and .json files in those node_modules
+!e2e/**/node_modules/**/*.js
+!e2e/**/node_modules/**/*.json
+

docs/shareable-configs.md

@@ -4,27 +4,122 @@ Shareable configs are configurations that you can use and extend from. They can
 
 To use a shareable config, you have to add it to your Solhint configuration:
 
-```
+```json
+{
   "extends": ["solhint:recommended", "protofire"]
+}
+```
+
+This example shows the two types of shareable configs that you can use:
+
+- **Built-in Solhint configs**, which start with `solhint:` (e.g. `solhint:recommended`, `solhint:all`)
+- **Shareable configs installed from npm**
+
+
+## Using npm shareable configs
+
+Unscoped shareable configs are npm packages prefixed with `solhint-config-`.
+
+For example, this configuration:
+
+```json
+{
+  "extends": ["protofire"]
+}
+```
+
+Will load the package:
+
+```
+solhint-config-protofire
+```
+
+which must be installed beforehand:
+
+```
+npm install solhint-config-protofire
+```
+
+You can also reference the full package name explicitly:
+
+```json
+{
+  "extends": ["solhint-config-protofire"]
+}
+```
+
+Shareable configs are resolved from the project's `node_modules` directory (the current working directory), even when Solhint is installed globally.
+
+
+## Scoped shareable configs
+
+Solhint also supports **scoped** shareable configs.
+
+Given the npm package:
+
+```
+@scope/solhint-config-myconfig
+```
+
+You can use it in your configuration as:
+
+```json
+{
+  "extends": ["@scope/solhint-config-myconfig"]
+}
+```
+
+For convenience, Solhint also supports the ESLint-style shorthand:
+
+```json
+{
+  "extends": ["@scope/myconfig"]
+}
 ```
 
-This example shows the two types of shareable configs that you can use: the ones included with Solhint, that start with `solhint:`, and the ones that you can install from npm. The latter are packages that are prefixed with `solhint-config-`, so in this case the package would be installed doing `npm install solhint-config-protofire` but used as just `protofire` when adding it.
+Which resolves to:
+
+```
+@scope/solhint-config-myconfig
+```
+
+Note: Only package-level scoped configs are supported (`@scope/name`). Deep paths such as `@scope/name/extra` are not supported.
+
 
 ## Creating your own shareable config
 
 Shareable configs are regular npm packages. There are only two conditions:
 
-- The name of the package must start with `solhint-config-`
-- The package must export a regular object with the same structure as a regular configuration object (i.e. the one in your `.solhint.json`).
+- The package name must start with `solhint-config-`  
+  (for scoped packages: `@scope/solhint-config-*`)
+- The package must export a regular object with the same structure as a standard Solhint configuration (i.e. the one in your `.solhint.json`)
 
 For example, a very minimal `index.js` in this package could be:
 
-```javascript
+```js
 module.exports = {
   rules: {
     'max-line-length': 80
   }
 }
 ```
 
-After creating this package you can publish it to npm to make it available for everyone.
+After creating this package, you can publish it to npm to make it available for everyone.
+
+
+## Configuration inheritance
+
+Solhint supports **hierarchical configuration**.
+
+When linting a file, configurations are merged in the following order:
+
+1. The project root configuration
+2. Each parent directory configuration
+3. The directory containing the file (**highest precedence**)
+
+For each configuration file, any `extends` entries are resolved first, and then all configurations are merged according to directory hierarchy.
+
+Rules and settings defined in deeper directories **override** those from higher-level directories and from extended configs.
+
+In short:  
+**`extends` are resolved first, directory hierarchy is applied after, and the closest config always wins.**

e2e/14-shareable-config/filesystem01/project/.solhint.json

@@ -0,0 +1,3 @@
+{
+  "extends": ["@test/demo"]
+}

e2e/14-shareable-config/filesystem01/project/contracts/EmptyBlocks.sol

@@ -0,0 +1,6 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+contract A {
+    function f() public {}
+}

e2e/14-shareable-config/filesystem01/project/node_modules/@test/solhint-config-demo/index.js

@@ -0,0 +1,3 @@
+{
+  "extends": ["@test/base"]
+}

e2e/14-shareable-config/filesystem02/project/.solhint.json

@@ -0,0 +1,6 @@
+{
+  "rules": {
+    "max-line-length": ["error", 80]
+  }
+}
+

e2e/14-shareable-config/filesystem02/project/contracts/.solhint.json

@@ -0,0 +1,4 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+contract A { function f() public { uint x = 1; uint y = 2; uint z = 3; uint w = 4; } function g() public { } }