add FAQ and useful info to contribution guidelines (#1047)

* add FAQ and useful info to contribution guidelines

* link to path filtering wiki, add FAQ to ToC

* address josselin's feedback

* update docs:

CONTRIBUTING.md

@@ -20,6 +20,24 @@ Some pull request guidelines:
 - Fill out the pull request description with a summary of what your patch does, key changes that have been made, and any further points of discussion, if applicable.
 - Title your pull request with a brief description of what it's changing. "Fixes #123" is a good comment to add to the description, but makes for an unclear title on its own.
 
+## Directory Structure
+
+Below is a rough outline of slither's design:
+```text
+.
+├── analyses # Provides additional info such as data dependency 
+├── core # Ties everything together
+├── detectors # Rules that define and identify issues 
+├── slither.py # Main entry point
+├── slithir # Contains the semantics of slither's intermediate representation
+├── solc_parsing # Responsible for parsing the solc AST
+├── tools # Miscellaneous tools built on top of slither
+├── visitors # Parses expressions and converts to slithir
+└── ...
+```
+
+A code walkthrough is available [here](https://www.youtube.com/watch?v=EUl3UlYSluU).
+
 ## Development Environment
 Instructions for installing a development version of Slither can be found in our [wiki](https://github.com/crytic/slither/wiki/Developer-installation).
 
@@ -46,6 +64,7 @@ For each new detector, at least one regression tests must be present.
 - Create a test in `tests`
 - Update `ALL_TEST` in `tests/test_detectors.py`
 - Run `python ./tests/test_detectors.py --generate`. This will generate the json artifacts in `tests/expected_json`. Add the generated files to git.
+  - If updating an existing detector, identify the respective json artifacts and then delete them, or run `python ./tests/test_detectors.py --overwrite` instead.
 - Run `pytest ./tests/test_detectors.py` and check that everything worked.
 
 To see the tests coverage, run `pytest  tests/test_detectors.py  --cov=slither/detectors --cov-branch --cov-report html`

README.md

@@ -13,6 +13,7 @@ Slither is a Solidity static analysis framework written in Python 3. It runs a s
 - [Tools](#tools)
 - [How to Install](#how-to-install)
 - [Getting Help](#getting-help)
+- [FAQ](#faq)
 - [Publications](#publications)
 
 ## Features
@@ -128,6 +129,8 @@ Num | Detector | What it Detects | Impact | Confidence
 74 | `too-many-digits` | [Conformance to numeric notation best practices](https://github.com/crytic/slither/wiki/Detector-Documentation#too-many-digits) | Informational | Medium
 75 | `constable-states` | [State variables that could be declared constant](https://github.com/crytic/slither/wiki/Detector-Documentation#state-variables-that-could-be-declared-constant) | Optimization | High
 76 | `external-function` | [Public function that could be declared external](https://github.com/crytic/slither/wiki/Detector-Documentation#public-function-that-could-be-declared-external) | Optimization | High
+77 | `arbitrary-send-erc20` | [Detect when `msg.sender` is not used as `from` in transferFrom](https://github.com/trailofbits/slither/wiki/Detector-Documentation#arbitrary-send-erc20)
+78 | `arbitrary-send-erc20-permit` | [Detect when `msg.sender` is not used as `from` in transferFrom in conjuction with permit](https://github.com/trailofbits/slither/wiki/Detector-Documentation#arbitrary-send-erc20-permit)
 
 For more information, see
 - The [Detector Documentation](https://github.com/crytic/slither/wiki/Detector-Documentation) for details on each detector
@@ -146,6 +149,7 @@ For more information, see
 - `cfg`: [Export the CFG of each functions](https://github.com/trailofbits/slither/wiki/Printer-documentation#cfg)
 - `function-summary`: [Print a summary of the functions](https://github.com/trailofbits/slither/wiki/Printer-documentation#function-summary)
 - `vars-and-auth`: [Print the state variables written and the authorization of the functions](https://github.com/crytic/slither/wiki/Printer-documentation#variables-written-and-authorization)
+- `when-not-paused`: [Print functions that do not use `whenNotPaused` modifier](https://github.com/trailofbits/slither/wiki/Printer-documentation#when-not-paused).
 
 To run a printer, use `--print` and a comma-separated list of printers.
 
@@ -158,6 +162,7 @@ See the [Printer documentation](https://github.com/crytic/slither/wiki/Printer-d
 - `slither-flat`: [Flatten a codebase](https://github.com/crytic/slither/wiki/Contract-Flattening)
 - `slither-check-erc`: [Check the ERC's conformance](https://github.com/crytic/slither/wiki/ERC-Conformance)
 - `slither-format`: [Automatic patch generation](https://github.com/crytic/slither/wiki/Slither-format)
+- `slither-read-storage`: [Read storage values from contracts](./slither/tools/read_storage/README.md)
 
 See the [Tool documentation](https://github.com/crytic/slither/wiki/Tool-Documentation) for additional tools.
 
@@ -208,11 +213,23 @@ Feel free to stop by our [Slack channel](https://empireslacking.herokuapp.com) (
 
 * The [SlithIR documentation](https://github.com/trailofbits/slither/wiki/SlithIR) describes the SlithIR intermediate representation.
 
+## FAQ
+
+How do I exclude mocks or tests?
+- View our documentation on [path filtering](https://github.com/crytic/slither/wiki/Usage#path-filtering).
+
+How do I fix "unknown file" or compilation issues?
+- Because slither requires the solc AST, it must have all dependencies available.
+If a contract has dependencies, `slither contract.sol` will fail.
+Instead, use `slither .` in the parent directory of `contracts/` (you should see `contracts/` when you run `ls`).
+If you have a `node_modules/` folder, it must be in the same directory as `contracts/`. To verify that this issue is related to slither,
+run the compilation command for the framework you are using e.g `npx hardhat compile`. That must work successfully;
+otherwise, slither's compilation engine, crytic-compile, cannot generate the AST.
+
 ## License
 
 Slither is licensed and distributed under the AGPLv3 license. [Contact us](mailto:opensource@trailofbits.com) if you're looking for an exception to the terms.
 
-
 ## Publications
 
 ### Trail of Bits publication