konobi / kwalitee Goto Github PK

We should add a library checker that checks to ensure that all dependencies and devdependencies are actually added to the package.json. We should also check for require paths, to ensure that there are no surprises based on where the script/library is run from.

Yes, short paths are nice, but readable folder names that clearly communicate what's inside are nicer.

Have an index.js file in each importable local folder with the public exports of that folder, like init.py is used for in Python. This way you can directly import that folder without needing to specify the file (require('folder') vs. require('folder/file.js')).

To an extent I can agree that containing tests in a subfolder is useful as a quality metri, but requiring a name for that subfolder is plain awful. It doesn't speak at all to any kind of quality metric about the code itself, only shoehorns authors who are paying attention into a rigid structure, and authors who aren't paying attention into falsely low scores.

Two alternative suggestions:

1. The intent of this checker seems to be about code organization / keeping things tidy. This can be achieved without any specific structure by simply testing the number of "loose files" in the root directory. This should be done on the product of npm packaging so that npmignore is accounted for, and possibly excluding common files such as grunt, gulp, bower, package.json, etc. This method has the advantage of not penalizing small, self-contained packages that only have one file and one test file, for example.

2. Curate a list of acceptable folder names and be open to adding others to the list, as long as they serve the intended purpose. Some opinion is okay with this method (for example "no, 't' is not a good folder name), but it shouldn't be overbearing.

Hi

Just replying to your message on Twitter yesterday (in my TZ).

So I was referring to my #1 issue with some (thankfully a minority) not being semver (http://semver.org/) compliant (despite claiming to be). This would usually manifest most often in publishing of updates under say a patch release - this can cause serious breakage for packages which depend on the offending package.

Also a problem from time to time is package authors door a bad job of their dependency versioning, most often what I see is users requiring a package with a version of "*". Clearly this is a bad idea as a major release in the dependency could easily break the integration/usage.

Does that explain in the level of detail you need?

Another issue which springs to mind is people not stating a license for their software. This means that for example, at work, I basically can't use the package as it has no terms of usage.

Cheers

Putting your entry code in more folders just makes it harder for everyone else to get to. I mean, unless you want to hide your code I guess. :)

If you have other files required by your index.js, or whichever other entry file, that's fine to go into lib/ or other top-level files, if it doesn't belong in another module.

From: https://twitter.com/konobi/status/639536896968892416

If there is npm config supplied in the package.json, we should ensure that it's actually used.

Add common IDE folder names, MacOS X system files/folders like .Trashes or .DS_STORE etc

This prevents accidental commits of files that should not be under version control without putting the burden on potential contributors

The "test" folder often needs to contain files that are valid JavaScript but not valid tests (mocks, "karma.main.js"-kinda files, test-related helpers, etc).
Having something unique in the names of test files ('.spec.js', '.tap.js', etc) makes globbing much easier and keeps test-runner configuration simple.
It also makes it easier to apply different linting rules to different types of files independent of the folder they are in.

NPM warns about this, but it can be reasonably considered a quality-worthy consideration. Also, this module fails it.

Per your request:

• Of course, follow semver scrupulously. Known breaking changes must bump a major version. Any functionality or API additions must be in a minor bump. Everything else is a patch. Any breakages discovered must be rolled back and ported to the next major version. etc.
• npm install should be 100% of what's required in a given module to install all of its dependencies and/or dev dependencies
• npm test should always run tests
• npm explore foo && npm test should always run foo's tests (ie, always publish test files)
• Any build steps or compilation must be done prior to publishing - ie, coffeescript, babel, etc must never be required at runtime to use a module
• Any important project-related tasks should be discoverable from the scripts hash in package.json. Makefiles (or any ripoffs of same) are totally fine, but I shouldn't need to know how to use those to run 100% of important tasks: npm run foo can alias to make foo, for example.
• Good documentation: include a readme.
• package.json must always point to the git repo, to where issues can be filed, and must always include at least one license designation.

We should add a publish checker, to ensure that things like coffeescript, babel and the like have been compiled to JS before publishing.

While there are issues with linting and personal preference, there are many checks that are valuable, such as ensuring use of '===' when evaluating values like null, undefined, etc.

The default value for the start script is to exec node server.js, so if there's no specific start script on package.json and the package has only a single executable (like a CLI), that executable file should be named server.js so it can be launched with npm in a standard and homogeneous way.

There are places where things like deprecation notices have been added to the README on github, but this hasn't been published to npm. We should work out a way of dealing with these sorts of things.

For native addons, there's several checks that we should add. For example, ensuring the use of something like the nan package and the like.

There will be more, but we should field ideas from folks who are more familiar with native addons.

It's still the default "there are no tests"

Some packages have an empty object on devDependencies, that's ugly. The same happens when they set explicitly some fields with their default values, that's cumbersome.

file require()s entries should be at the top of the page, maybe with interlazed with some variables definitions, but in the recomended order: Node.js build-ins, third-party modules, and last modules on the same project. This can be easily identified by the usage of relative paths on the requires.