feat(jsdoc-core): add @jsdoc/core.util.fs.lsSync

packages/jsdoc-core/lib/util/fs.js

@@ -0,0 +1,19 @@
+/**
+ * @module @jsdoc/util/lib/fs
+ */
+
+const _ = require('lodash');
+const klawSync = require('klaw-sync');
+const path = require('path');
+
+exports.lsSync = ((dir, opts = {}) => {
+    const depth = _.has(opts, 'depth') ? opts.depth : -1;
+
+    const files = klawSync(dir, {
+        depthLimit: depth,
+        filter: (f => !path.basename(f.path).startsWith('.')),
+        nodir: true
+    });
+
+    return files.map(f => f.path);
+});

packages/jsdoc-core/lib/util/index.js

@@ -1,5 +1,7 @@
 const cast = require('./cast');
+const fs = require('./fs');
 
 module.exports = {
-    cast
+    cast,
+    fs
 };

packages/jsdoc-core/package.json

@@ -23,7 +23,9 @@
   },
   "dependencies": {
     "cosmiconfig": "^6.0.0",
+    "klaw-sync": "^6.0.0",
     "lodash": "^4.17.15",
+    "mkdirp": "^0.5.1",
     "ow": "^0.15.0",
     "strip-bom": "^4.0.0",
     "strip-json-comments": "^3.0.1",

packages/jsdoc-core/test/specs/lib/util/fs.js

@@ -0,0 +1,71 @@
+describe('@jsdoc/util/lib/fs', () => {
+    const mockFs = require('mock-fs');
+    const fsUtil = require('../../../../lib/util/fs');
+    const path = require('path');
+
+    afterEach(() => mockFs.restore());
+
+    it('has an lsSync method', () => {
+        expect(fsUtil.lsSync).toBeFunction();
+    });
+
+    describe('lsSync', () => {
+        beforeEach(() => {
+            mockFs({
+                head: {
+                    eyes: '',
+                    ears: '',
+                    mouth: '',
+                    nose: '',
+                    shoulders: {
+                        knees: {
+                            meniscus: '',
+                            toes: {
+                                phalanx: '',
+                                '.big-toe-phalanx': ''
+                            }
+                        }
+                    }
+                }
+            });
+        });
+
+        const cwd = process.cwd();
+
+        function resolvePaths(files) {
+            return files.map(f => path.join(cwd, f)).sort();
+        }
+
+        const allFiles = resolvePaths([
+            'head/eyes',
+            'head/ears',
+            'head/mouth',
+            'head/nose',
+            'head/shoulders/knees/meniscus',
+            'head/shoulders/knees/toes/phalanx'
+        ]);
+
+        it('gets all non-hidden files from all levels by default', () => {
+            const files = fsUtil.lsSync(cwd).sort();
+
+            expect(files).toEqual(allFiles);
+        });
+
+        it('limits recursion depth when asked', () => {
+            const files = fsUtil.lsSync(cwd, { depth: 1 }).sort();
+
+            expect(files).toEqual(resolvePaths([
+                'head/eyes',
+                'head/ears',
+                'head/mouth',
+                'head/nose'
+            ]));
+        });
+
+        it('treats a depth of -1 as infinite', () => {
+            const files = fsUtil.lsSync('head', { depth: -1 }).sort();
+
+            expect(files).toEqual(allFiles);
+        });
+    });
+});

packages/jsdoc-core/test/specs/lib/util/index.js

@@ -12,4 +12,12 @@ describe('@jsdoc/core/lib/util', () => {
             expect(util.cast).toBe(cast);
         });
     });
+
+    describe('fs', () => {
+        it('is lib/util/fs', () => {
+            const fs = require('../../../../lib/util/fs');
+
+            expect(util.fs).toBe(fs);
+        });
+    });
 });