Srcy
Check project paths for files that are referenced but do not exist and files that exist but are not referenced.
Installation
At project level
npm install srcy
Globally (as an optional extra)
npm install -g srcy
Usage
Create a srcy.conf.json file at the root level of any project that you wish to check. See Configuration.
At this point srcy can be run manually from the command line with:
node npm_modules/srcy/srcy.js
Or if installed both locally and globally you can use:
srcy
To include Srcy as part of your test suite it is recommended you add this reference to your package.json scripts object.
"scripts": {
"srcy": "node node_modules/srcy/srcy.js"
}
Or if you have Srcy installed globally on your test environment you can use:
"scripts": {
"srcy": "srcy"
}
Configuration
Create a config file
To run Srcy your project will need a srcy.conf.json file at the project root. You can generate an (almost) empty config file if you have installed Srcy globally by running:
srcy init
If a config already exists you can over-write it with the default one using:
srcy init -f
The generated file should look like this:
{
"refs": {
"whitelist": false,
"blacklist": [],
"notTypes": [],
"replace": {},
"ignore": [],
"wildcards": []
},
"resources": {
"root": "",
"folders": [],
"types": ["gif", "png", "jpg", "svg"],
"ignore": []
}
}
Editing the config file
Srcy will catch many issues for you like this but it's highly unlikely that you will have a robust check in place without further configuration.
Rather than aiming to code a solution to every possible variation within a project set up, Srcy is designed to be highly configurable allowing you to tune it to the specifics of your project.
refs
This section is for configuring how Srcy searches your project code base for references to files.
refs.whitelist
default value: false
type when populated: array
If you wish to specify folders or files that Srcy should check and only check then add them to whitelist attribute as an array such as:
"whitelist": ["web", "css", "js"]
If no whitelist is specified Srcy will just start at the project root and check all files and folders that aren't blacklisted.
refs.blacklist
default value: []
In most cases you won't want to check every file in your project and doing so will effect the performance of Srcy. Add any files or folders that you do not wish checked to this array, such as:
"blacklist": ["node_modules", "test", "README.md", "package.json", "web/images"]
refs.notTypes
default value: []
In addition to blacklisting specific files or folders you can use the notTypes attribute to ensure Srcy does not check files of a certain type. You may generate .css files from some other type of file and thus wish to ignore all css files:
notTypes: ["css"]
refs.replace
default value: {}
In some cases you may wish to replace a file reference with one or many others. N.B replace takes precedence over wildcards.
You may have JavaScript files that reference resources dynamically such as this:
"img/buttons/" + onOffState + ".gif"
You may wish to specify that this reference should refer to two separate resource files:
- "img/buttons/on.gif"
- "img/buttons/off.gif"
In order to achieve this you would set the replace attribute to be:
"replace": {
"img/buttons/' + onOffState + '.gif": [
'img/buttons/on.gif',
'img/buttons/off.gif'
]
}
Both files will now be matched against your project set up.
refs.ignore
default value: []
You may wish to ignore certain resource references within your code base, perhaps they refer to external resources with similar matching patterns or are described as plain text and not actually part of your project. Any references you wish to exclude from Srcy's checks should be listed as such:
"ignore": ["img/example.gif", "img/someOtherSitesLogo.gif"]
refs.wildcards
More powerful than replace, wildcards allows you to match and replace file references based on a regular expression. You can create your own matchers but some popular examples are included in the wildcards section.
If for example you are using Jade templates you may wish to specify a Jade variable as a wildcard such as:
"wildcards": ["#{.*?}"]
So that a reference such as:
"img/weather/#{weather}.png"
Would be replaced with a reference to every image inside the weather folder that could possibly be a match for that. If you had the following folder structure:
img -
| - weather
| - sunny.png
| - cloudy.png
| - sunny.gif
| - cloudy.gif
the files:
- "img/weather/sunny.png"
- "img/weather/cloudy.png"
would be added as references.
resources
This section is for configuring the way in which Srcy matches static files in your project.
resources.root
default value: ""
To assist Srcy in finding all your static files a root folder needs to be specified. Something such as:
"./public"
resources.folders
default value: []
Here you list all the folders within your root folder that you expect Srcy to look for files that you wish to be checked. Such as:
"folders": ["img", "pdfs"]
resources.types
default value: ["gif", "png", "jpg", "svg"]
Srcy will only check for files with the suffixes within this array, add any additional file types that you want to check.
resources.ignore
default value: []
If you wish to exclude any files from the resource search you can specify them here.
"ignore": ["img/archive/old-logo.gif", "img/archive/christmas-logo.gif"]
Wildcards
As common or popular wildcards come to light they will be added here. Please feel free to submit ones that you have used (and ideally tested in production) here to build up a useful reference for others.
Jade wildcards
To replace Jade variable references such as:
"img/weather/#{weather}.gif"
use:
"#{.*?}"
matches:
- "img/weather/sunny.gif"
- "img/weather/cloudy.gif"