Error & debug handling for developers

[ErisDS]

#Refs #7491

I've heavily reworked how themes are loaded, validated & how they work in general over the course of the last couple of weeks.

This has resulted in what is sort of a bug and sort of a concept that hasn't been worked through correctly.

Bug report:

Starting Ghost with an invalid theme results in a small log warning that says "The active theme is invalid". This is just a warning, because the admin panel will still load. This is the correct behaviour, although the warning should probably be bigger and clearer.

However, when you finally come to try to access a page of your blog, the error you get says:

"The currently active theme is missing".

It's missing because due to the theme being invalid, we didn't load it in. So now Ghost (somewhat correctly) thinks your active theme isn't present.

For those users who miss the invalid warning (which will be pretty much everyone) this will be the first message they see, and it's effectively wrong and very confusing.

Where it gets interesting

There are 2 cases for which an active theme can be invalid:

• CASE 1: you are a developer updating the theme files locally on your machine / dev server.
• CASE 2: we do an upgrade in which gscan rules change

CASE 1: only affects developers / development mode. CASE 2: will impact all users and is effectively us doing something wrong (we should have known that this would happen and ensured the theme was updated first), but the impact is huge - the whole blog will refuse to render.

Note that the reason why the error message is wrong is because we don't activate the invalid theme. This means we don't keep reference to the gscan output or state of the theme, and so in the current iteration we cannot tell the user a better error. It's just missing.

Even worse, if you're a developer working on a theme, the most common error that will happen is malforming some handlebars, in which case you want handlebars to give you the compile errors when you try to render the page, not gscan to fail to boot. However, gscan will detect the error, the theme won't activate, and you'll be left with gscan errors, which we currently don't even output 😖

Potential solution

There are 3 mechanisms for activating a theme:

• on boot
• on activate
• on uploading with override

Both of these cases ONLY impact on the boot. This got me thinking we need to further evolve the concept of "mounting" and "activating".

If a theme is being actively activated by a user (via activate or upload endpoints), we should return the output from gscan and go no further.

On boot, we need a more evolved approach. I think the rules need to be something like this:

DEV MODE

• Gscan warning -> log Gscan warning, mount
• Gscan compile error -> log Gscan error, mount -> allow handlebars to attempt compile
• Gscan other error -> log Gscan error, mount with error -> allow gscan error to be rendered as 500

PROD MODE

• Gscan warning -> output, mount
• Gscan error -> log Gscan error, mount with error -> allow gscan error to be rendered as 500

I'm not 100% sure, I first need to implement a way to pass through gscan errors and see what they can look like rendered.

• first task: go over gscan errors and mark fatal and none fatal errors (K)
• if bootstrap and theme is invalid, navigate to blog frontend and you will see "theme is missing" -> change to theme is invalid and show errors if possible? (A)
• usage of valid hbs helper with invalid usage (K)
• differentiate other errors from compile errors - show other errors (which are probably gscan errors) as 500 errors in frontend (A)
• differentiate fatal errors from none fatal errors in Ghost (K)
• consider/check usability to only show fatal errors in production mode when activating/uploading theme (A)
• when hbs compile errors, mount in dev and show hbs error, don't mount and show gscan error in prod (K)
• produce gscan warning and check bootstrap behaviour (A)
• log errors on bootstrap if theme is invalid
• optimise admin report - structure a little (e.g. little boxes per error, show (and order) fatal error attribute) (J+A+K)
• look at gscan warnings again

[ErisDS]

I'm still seeing some problems with theme error handling, whereby Ghost shows "the currently active theme X is missing" when the theme is fine and something else is wrong.

Reproduction case A - gscan is broken:

1. uninstall the gscan module
2. npm link gscan to a slightly older version that doesn't have custom templates

Reproduction case B - invalid node version:

• Users trying to use node v8 get this incorrect error