DISCUSSION: Standardize errors/non-data communication between tools.

[MaikuMori]

Currently there is no standard way to pass errors between toolchains, srclib and the caller.

Since all communication is already done using JSON we should probably stick to that.

I propose something like:

{
    "success": false,
    "info": 0,
    "warnings": 1,
    "errors": 1,
    "critical": 1,
    "issues": [
        {
            "severity": "warning",
            "type": "source",
            "line": 13,
            "column": 10,
            "file": "~/Projects/rainbow/__init__.py",
            "issue": "Imported external dependency is not present in `requirements.txt`. Generated output may be affected.",
            "toolchain": "sourcegraph.com/sourcegraph/srclib-python",
            "command": "srclib-python scan  ~/Projects/rainbow > srclib-python graph"
        },
        {
            "severity": "error",
            "type": "fine",
            "file": "~/Projects/rainbow/pot.py",
            "issue": "File doesn't contain gold. Cannot proceed.",
            "toolchain": "github.com/xyz/greedchain",
            "command": "cat something > greedchain graph"
        },
        {
            "severity": "critical",
            "type": "toolchain",
            "stdout": "",
            "stderr": "Whoops!",
            "issue": "Toolchain exited with error code 666.",
            "toolchain": "github.com/xyz/failchain",
            "command": "failchain fail something"
        }
    ]
}

Actual fields are obviously open to discussion. Need to gather some real output to come up with better fields/types.

Output is merged from multiple tools until it is presented to the caller. Communication is done over stderr, leaving stdout open for data communications as before. If the caller is a person we can also render the JSON to text.

Severity:

• info - Helpful messages. Tools output may be inaccurate. (Toolchian out of date, etc)
• warning - Processing can continue, but output most likely will be inaccurate.
• error - Expected error. Processing shouldn't continue (within the toolchain).
• critical - Unexpected/unhandled error. Processing can't continue.

Ideas, comments?

Related issues:

• Suppress install-std output unless there's an error #21
• Python toolchain installation silently fails #140

[dmitshur]

Currently there is no standard way to pass errors between toolchains, srclib and the caller.

Since all communication is already done using JSON we should probably stick to that.

In general, this sounds like a good thing to do!

[sqs]

This seems like it'd be useful for a combination of source code issues (e.g., lint-style output) and toolchain errors (e.g., errors in the way you configured your toolchain). Which is this intended for?

[MaikuMori]

@sqs, I was thinking it could be used for both of those cases and possibly more cases. Basically standardize non-data communication. That's why I included type into issues list. Later on it's easy to filter down just the information your specific code needs. Plugins can show different errors in different way (underline in source or show popup or something). On console you can hide some issues based on verbosity setting and so on.