progeny

Recursively finds dependencies of style and template source files.

Or configure it to do the same kind of thing with any other type of code file that has an import-type syntax.

Usage

progeny ([config]) (path, [sourceContents], callback)

progeny.Sync ([config]) (path, [sourceContents])

Call progeny with an optional configuration object, it returns a reusable function. Call that function with a path to a source file (and its source code if you already have it handy), and it will figure out all of that file's dependencies and sub-dependencies, passing an array of them to your callback. Or use the Sync API to get the results as a return value.

Result array has non-enumerable patterns property with an array of glob patterns found in source files' import statements.

Examples using path assume you already have var path = require('path');. You could just use strings like '/path/to/project', but you may run into cross-compatibility issues.

Quick and Simple

You can skip the config object and the source code, letting Progeny read the source from the file itself and apply a built-in configuration based on the file extension.

var progeny = require('progeny');
var filePath = path.join('path', 'to', 'project', 'style-or-template.pug');

// Async
progeny()(filePath, function (err, dependencies) {
    // use the dependencies array in here
});

// Sync
var dependencies = progeny()(filePath);

Configuration

There are built-in configurations already for css, sass/scss, less, stylus, pug/jade, slm, and proto. Configuration must be specified for any other formats. Feel free to submit Pull Requests to add default types, or improve the settings for the existing ones.

var progenyConfig = {
    // The file extension for the source code you want parsed
    // Will be derived from the source file path if not specified
    extension: 'styl',

    // Array of multiple file extensions to try when looking for dependencies
    extensionsList: ['scss', 'sass'],

    // Regexp to run on each line of source code to match dependency references
    // Make sure you wrap the file name part in (parentheses)
    regexp: /^\s*@import\s+['"]?([^'"]+)['"]?/,

    // File prefix to try (in addition to the raw value matched in the regexp)
    prefix: '_',

    // Matched stuff to exclude: string, regex, or array of either/both
    exclusion: /^compass/,

    // In case a match starts with a slash, the absolute path to apply
    rootPath: path.join('path', 'to', 'project'),

    // Other paths to check for possible dependency resolution
    altPaths: [
      path.join('path', 'to', 'shared'),
      path.join('path', 'to', 'common')
    ],

    // An array of regexps to run in series for more complex dependency parsing
    // Useful for matching multiple dependencies from one, possibly mult-line,
    // statement. All regexps except the last one must use the global flag.
    multipass: [
        /@import[^;]+;/g,
        /\s*['"][^'"]+['"]\s*,?/g,
        /(?:['"])([^'"]+)/
    ],

    // By default the list of paths progeny provides will be limited to files
    // actually found in the file system. Use this option to get every possible
    // path progeny thinks a depencency could be located at.
    potentialDeps: true,

    // By default progeny will strip all line comments like "// ..." and
    // multiline comments like "/* ... */". You could disable this behavior.
    skipComments: true;

    // Custom resolver allows to preprocess dependency name. For example, webpack
    // has well known way to reference node_modules-related path with ~ in the
    // beginning of import name.
    // Return true, undefined or null to accept dependency without changes.
    // Return false to reject dependency.
    // Return new filename to override dependency.
    resolver: function (depFilename, parentDir, parentFilename) {
      if (depFilename.startsWith('~')) {
        var absPath = path.resolve(path.join('.', 'node_modules', depFilename.substr(1)));
        return path.relative(parentDir, absPath);
      }
    },

    // Print dependency resolution information to console.log
    debug: true
};

More Examples

Process a list of files:

var progeny = require('progeny');
var getDependencies = progeny(progenyConfig);
myFiles.forEach(function (file) {
    getDependencies(file.path, file.source, function (err, deps) {
        if (err) throw new Error(err);
        file.dependencies = deps;
    });
});

Multiple configs:

var getDefaultDependencies = progeny();
var getCustomDependencies = progeny({
    extension: 'foo',
    regexp: /([^\s,]+)/
});

Process source code from a string without its file path:

var mySourceString; // assume this contains valid source code
progeny({
    // extension and rootPath must be specified for this to work
    // also need regexp if extension not one of the predefined ones
    extension: 'less',
    rootPath: path.join('path', 'to', 'project')
})(null, mySourceString, function (err, deps) {});

Change Log

See release notes page on GitHub

License

MIT