fix: scoped packs for shareable configs

Author: dbale-altoros

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/filesystem02/project/.solhint.json

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

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

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

e2e/14-shareable-config/filesystem02/project/contracts/A.sol

@@ -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 { } }

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

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

e2e/14-shareable-config/filesystem03/project/contracts/deep/.solhint.json

@@ -0,0 +1,6 @@
+{
+  "rules": {
+    "max-line-length": ["error", 60],
+    "no-empty-blocks": "off"
+  }
+}

e2e/14-shareable-config/filesystem03/project/contracts/deep/B.sol

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

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

@@ -0,0 +1,4 @@
+{
+  "extends": ["a", "b"]
+}
+