cook-ssg 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +445 -0
  3. package/bin/cook.js +66 -0
  4. package/package.json +75 -0
  5. package/patches/jsdom-fetch-fix.js +52 -0
  6. package/scripts/build.js +212 -0
  7. package/scripts/dev.js +119 -0
  8. package/scripts/plugins/apply-template.js +226 -0
  9. package/scripts/plugins/auto-components.js +215 -0
  10. package/scripts/plugins/bundle.js +338 -0
  11. package/scripts/plugins/copy-src.js +89 -0
  12. package/scripts/plugins/create-dir-from-file.js +144 -0
  13. package/scripts/plugins/create-dist.js +55 -0
  14. package/scripts/plugins/custom-plugins.js +118 -0
  15. package/scripts/plugins/declarative-shadow-dom.js +164 -0
  16. package/scripts/plugins/escape-code-blocks.js +54 -0
  17. package/scripts/plugins/generate-formats.js +361 -0
  18. package/scripts/plugins/generate-fragments.js +126 -0
  19. package/scripts/plugins/generate-sitemap-xml.js +216 -0
  20. package/scripts/plugins/minify-src.js +253 -0
  21. package/scripts/plugins/optimize-images.js +389 -0
  22. package/scripts/plugins/process-html-frontmatter.js +75 -0
  23. package/scripts/plugins/process-markdown.js +384 -0
  24. package/scripts/plugins/repeat-collection.js +296 -0
  25. package/scripts/plugins/replace-components.js +496 -0
  26. package/scripts/plugins/replace-external-link-protocol.js +171 -0
  27. package/scripts/plugins/replace-include.js +273 -0
  28. package/scripts/plugins/replace-inline.js +217 -0
  29. package/scripts/plugins/replace-template-strings.js +121 -0
  30. package/scripts/plugins/set-active-links.js +175 -0
  31. package/scripts/utils/config/config.js +277 -0
  32. package/scripts/utils/get-src/get-src.js +241 -0
  33. package/scripts/utils/logger/logger.js +47 -0
  34. package/scripts/utils/performance/performance.js +35 -0
  35. package/scripts/utils/spinner/spinner.js +112 -0
  36. package/scripts/utils/timer/timer.js +40 -0
  37. package/scripts/utils/util/util.js +719 -0
@@ -0,0 +1,719 @@
1
+ // IMPORTS
2
+ // ----------------------------------
3
+ import chalk from 'chalk';
4
+ import fs from 'fs-extra';
5
+ import cliCursor from 'cli-cursor';
6
+ import cliSpinners from 'cli-spinners';
7
+ import v8 from 'node:v8';
8
+ import { lstatSync, readdirSync } from 'node:fs';
9
+ import { JSDOM } from 'jsdom';
10
+
11
+ import Logger from '../logger/logger.js';
12
+ import Spinner from '../spinner/spinner.js';
13
+ import Timer from '../timer/timer.js';
14
+
15
+ // BUILD CONFIG
16
+ import { activeLink, convertPageToDirectory, includeAttr, inlineAttr } from '../config/config.js';
17
+
18
+ const cwd = process.cwd();
19
+
20
+ // JSDOM CONFIG
21
+ // ----------------------------------
22
+ // https://github.com/jsdom/jsdom
23
+ const jsdom = {
24
+ baseUrl: 'https://localhost',
25
+ dom: newJSDOM,
26
+ frag: newFrag,
27
+ }
28
+
29
+ // STATIC CONFIG
30
+ // ----------------------------------
31
+ // Attribute values
32
+ const attr = {
33
+ active: convertToKebab(activeLink && activeLink.activeState, 'space') || 'active',
34
+ activeParent: convertToKebab(activeLink && activeLink.parentState, 'space') || 'active-parent',
35
+ include: includeAttr ? [includeAttr, `data-${includeAttr}`] : ['include', 'data-include'],
36
+ inline: inlineAttr ? [inlineAttr, `data-${inlineAttr}`] : ['inline', 'data-inline'],
37
+ }
38
+
39
+ // The default path types to target in `replace-external-link-protocol.js`
40
+ // if not defined by the user in the config file
41
+ const replaceExternalLinkProtocolDefaults = ['cdn', 'www'];
42
+
43
+
44
+ // EXPORT
45
+ // ----------------------------------
46
+ export {
47
+ addDirectory,
48
+ addDynamicPage,
49
+ attr,
50
+ convertExternalLinks,
51
+ convertToCamel,
52
+ convertToCapSpaces,
53
+ convertToKebab,
54
+ createDirectory,
55
+ customError,
56
+ customKill,
57
+ deepClone,
58
+ encodeTag,
59
+ escapeUrlString,
60
+ fakePromise,
61
+ getFileName,
62
+ getFileParts,
63
+ getFilePath,
64
+ getPaths,
65
+ getSelector,
66
+ initLogging,
67
+ hasExtension,
68
+ isAllowedType,
69
+ isExtension,
70
+ jsdom,
71
+ promiseAll,
72
+ replaceExternalLinkProtocolDefaults,
73
+ runFileLoop,
74
+ setSrc,
75
+ skipped,
76
+ updatePage,
77
+ validatePageChange,
78
+ };
79
+
80
+ // Default export for backward compatibility
81
+ export default {
82
+ addDirectory,
83
+ addDynamicPage,
84
+ attr,
85
+ convertExternalLinks,
86
+ convertToCamel,
87
+ convertToCapSpaces,
88
+ convertToKebab,
89
+ createDirectory,
90
+ customError,
91
+ customKill,
92
+ deepClone,
93
+ encodeTag,
94
+ escapeUrlString,
95
+ fakePromise,
96
+ getFileName,
97
+ getFileParts,
98
+ getFilePath,
99
+ getPaths,
100
+ getSelector,
101
+ initLogging,
102
+ hasExtension,
103
+ isAllowedType,
104
+ isExtension,
105
+ jsdom,
106
+ promiseAll,
107
+ replaceExternalLinkProtocolDefaults,
108
+ runFileLoop,
109
+ setSrc,
110
+ skipped,
111
+ updatePage,
112
+ validatePageChange,
113
+ };
114
+
115
+
116
+ // METHODS AND CONSTS
117
+ // ----------------------------------
118
+
119
+ /**
120
+ * @description Create directories in a path string if they don't already exist.
121
+ * Used before `fs.writeFile` to make sure destination exists.
122
+ * @param {Object} file
123
+ * @property {String} file.ext - The file's extension
124
+ * @property {String} file.name - The file's name
125
+ * @property {String} file.nameIfIndex - The file's name excluding `/index.html`
126
+ * @property {String} file.path - The file's full path
127
+ * @property {String} file.src - The file's source
128
+ * @private
129
+ */
130
+ function addDirectory(file) {
131
+ // Destructure object props
132
+ const {isDynamic,path} = file;
133
+ // Get the file path without the `.html`
134
+ // NOTE: For dynamically-created pages, they didn't run through the 'convert to directory' plugin
135
+ // So we need to do that here, by dropping the full `index.html`
136
+ // Static-page Example: `path/to/file.html` becomes `path/to/file`
137
+ // Dynamic-page Example: `path/to/file/index.html` becomes `path/to/file`
138
+ const splitOn = isDynamic ? 'index.html' : '.';
139
+ const pathSplit = path.split(splitOn)[0];
140
+ const filePath = pathSplit.match(/\/index$/) ? pathSplit.substring(4, -1) : pathSplit;
141
+ // Create the parent directories
142
+ fs.mkdirpSync(filePath);
143
+ }
144
+
145
+ /**
146
+ * @description For dynamically-generated pages (other Github repo, Wordpress, Drupal, etc.),
147
+ * instead of first creating the .html page with the converted source and then running the main file loop,
148
+ * we store the new page's path and source in memory. Then, during the main file loop, we read entries
149
+ * from our dynamic page-store instead of `fs.readFile` the page. This saves a duplication step, where
150
+ * we only need to `fs.writeFile` once for dynamic pages (file loop) instead of twice
151
+ * (before the file loop when the content was fetched and converted, and the file loop)
152
+ * @param {String} path - The path the dynamic .htnml page will be created at
153
+ * @param {String} src - The page's DOM source we'll use to populate the page
154
+ * @param {Object} store - Reference to the data store we'll add the page info entry to. Usually `this.data` from `/config/data.js`
155
+ * @private
156
+ */
157
+ function addDynamicPage(path,src,store) {
158
+ // Early Exit: Invalid data provided
159
+ if (!path) customKill(`addDynamicPage(): No page path provided`);
160
+ if (!src) customKill(`addDynamicPage(): No page source provided`);
161
+ if (!store) customKill(`addDynamicPage(): No data store provided`);
162
+ // If desired page collection property doesn't exist on the target store object, add it
163
+ if (!store.dynamicPages) store.dynamicPages = [];
164
+ // Add entry to data store
165
+ store.dynamicPages.push({ path, src });
166
+ }
167
+
168
+ /**
169
+ * @description Find all href="www.xxxx.com" links and add http:// protocol.
170
+ * By using the <base> tag, www links w/o a protocol are treated as internal (relative) links and will 404
171
+ * @param {*} source
172
+ * @returns {String}
173
+ * @private
174
+ */
175
+ function convertExternalLinks(source) {
176
+ return source.replace(/href="www/gi, 'href="http://www');
177
+ }
178
+
179
+ /**
180
+ * @description Convert 'single-spaced words' or 'kebab' strings to 'camel case'.
181
+ * @param {String} str - The string to convert.
182
+ * @param {String} type - The format the original string is in: single-spaced words, kebab.
183
+ */
184
+ function convertToCamel(str, type) {
185
+ if (!str) return;
186
+
187
+ switch (type) {
188
+ case 'kebab': return kebab();
189
+ case 'space': return spacedWords();
190
+ default: return str;
191
+ }
192
+
193
+ function kebab() {
194
+ const splitOnDash = str.split('-');
195
+ // Return formatted string
196
+ return format(splitOnDash);
197
+ }
198
+
199
+ function spacedWords() {
200
+ const splitOnSpace = str.split(' ');
201
+ // Lowercase words to normalize
202
+ const lowercase = splitOnSpace.map(t => t.toLowerCase());
203
+ // Return formatted string
204
+ return format(lowercase);
205
+ }
206
+
207
+ // ---
208
+
209
+ function format(arr) {
210
+ // Capitalize each word, but the first
211
+ const capitalize = arr.map((t,i) => i === 0 ? t : `${t.charAt(0).toUpperCase()}${t.substring(1)}`);
212
+ // Join words
213
+ return capitalize.join('');
214
+ }
215
+ }
216
+
217
+ /**
218
+ * @description Convert 'camel case' or 'kebab' strings to space-separated, capitlized words.
219
+ * @param {String} str - The string to convert.
220
+ * @param {String} type - The format the original string is in: camel case, kebab.
221
+ */
222
+ function convertToCapSpaces(str, type) {
223
+ if (!str) return;
224
+
225
+ switch (type) {
226
+ case 'camel': return camel();
227
+ case 'kebab': return kebab();
228
+ default: return str;
229
+ }
230
+
231
+ function camel() {
232
+ // Split string into array on each found capitalized word
233
+ const splitOnCaps = str.match(/([A-Z]?[^A-Z]*)/g).slice(0,-1);
234
+ // Capitalize the first word
235
+ splitOnCaps[0] = `${splitOnCaps[0].charAt(0).toUpperCase()}${splitOnCaps[0].substring(1)}`;
236
+ // Join the words with spaces
237
+ return splitOnCaps.join(' ');
238
+ }
239
+
240
+ function kebab() {
241
+ const splitOnDash = str.split('-');
242
+ // Capitalize each word
243
+ const capitalize = splitOnDash.map(t => `${t.charAt(0).toUpperCase()}${t.substring(1)}`)
244
+ // Return words joined with a space
245
+ return capitalize.join(' ');
246
+ }
247
+ }
248
+
249
+ /**
250
+ * @description Convert 'single-spaced words' or 'camel case' strings to 'kebab'.
251
+ * @param {String} str - The string to convert.
252
+ * @param {String} type - The format the original string is in: single-spaced words, camel case.
253
+ */
254
+ function convertToKebab(str, type) {
255
+ if (!str) return;
256
+
257
+ switch (type) {
258
+ case 'camel': return camel();
259
+ case 'space': return spacedWords();
260
+ default: return str;
261
+ }
262
+
263
+ function camel() {
264
+ // Split string into array on each found capitalized word
265
+ const splitOnCaps = str.match(/([A-Z]?[^A-Z]*)/g).slice(0,-1);
266
+ // Return formatted string
267
+ return format(splitOnCaps);
268
+ }
269
+
270
+ function spacedWords() {
271
+ const splitOnSpace = str.split(' ');
272
+ // Return formatted string
273
+ return format(splitOnSpace);
274
+ }
275
+
276
+ // ---
277
+
278
+ function format(arr) {
279
+ // lowercase each word
280
+ const lowercase = arr.map(t => t.toLowerCase());
281
+ // Join words with a dash
282
+ return lowercase.join('-');
283
+ }
284
+ }
285
+
286
+ /**
287
+ * @description Create directory hierarchy, if it doesn't already exist
288
+ * @param {String} path - The path to directory to create
289
+ * @private
290
+ */
291
+ async function createDirectory(path) {
292
+ try {
293
+ await fs.mkdirp(path);
294
+ }
295
+ catch (err) {
296
+ customKill(err, `Error creating directory(s) in: ${path}`);
297
+ }
298
+ }
299
+
300
+ /**
301
+ * @description Custom terminal error stack-trace message
302
+ * @param {Object} e - The error event
303
+ * @param {String} [label] - The console section label
304
+ * @private
305
+ */
306
+ function customError(e, label = 'Error') {
307
+ // Display custom message
308
+ console.log(chalk.bold.red(`\n${label}`));
309
+ // Display the error
310
+ console.log(e);
311
+ // Kill the node process to prevent completion
312
+ // Note: This is so it doesn't accidently get to the deploy phase and deploy w/ broken code
313
+ customKill('Build Stopped');
314
+ }
315
+
316
+ /**
317
+ * @description Custom terminal `kill -9 node` when you need to stop
318
+ * all terminal activity on exception/error.
319
+ * For example, a page needs to show fetched content. You don't want a deploy to occur
320
+ * if the source returned a rate limit, or didn't return anything and you don't want to
321
+ * show `N/A` or equivalent on screen.
322
+ * @param {String} msg - The console message before terminating
323
+ * @private
324
+ */
325
+ function customKill(msg) {
326
+ // Display terminal message and exit process
327
+ console.log(`\n${chalk.red(msg)}`);
328
+ process.exit(1);
329
+ }
330
+
331
+ /**
332
+ * @description Deep clone an object using the experimental, but native Serialization API in Node.js (https://nodejs.org/api/all.html#v8_serialization_api)
333
+ * @param {String} obj - The object to clone
334
+ * @returns {Object}
335
+ * @private
336
+ */
337
+ function deepClone(obj) {
338
+ return v8.deserialize(v8.serialize(obj));
339
+ }
340
+
341
+ /**
342
+ * @description Sanitize DOM tag for display. Replace `<` with `&lt;`
343
+ * @param {String} str - The string to sanitize
344
+ * @returs {String}
345
+ * @private
346
+ */
347
+ function encodeTag(str) {
348
+ return str.replace(/</g, '&lt;');
349
+ }
350
+
351
+ /**
352
+ * @description Simple escape method that escapes literal characters
353
+ * @param {String} url - The string to escape
354
+ * @example `/` becomes `\/`
355
+ * @example `.` becomes `\.`
356
+ * @returns {String}
357
+ * @private
358
+ */
359
+ function escapeUrlString(url) {
360
+ return url.replace(/\//g,'\\/').replace(/\./g,'\\.');
361
+ }
362
+
363
+ /**
364
+ * @description Create a test promise delay
365
+ * @param {Number} ms - The delay, in milliseconds
366
+ * @param {Boolean} throwError - Fake a rejected promise
367
+ * @returns {Object}
368
+ * @private
369
+ */
370
+ function fakePromise(ms, throwError) {
371
+ if (!throwError) return new Promise(resolve => setTimeout(resolve, ms));
372
+ else return Promise.reject('Could not resolve this')
373
+ }
374
+
375
+ /**
376
+ * @description Return filename from path
377
+ * @param {String} path - The file path (/path/to/file.ext)
378
+ * @param {String} distPath - The path to the /dist directory
379
+ * @returns {String}
380
+ * @private
381
+ */
382
+ function getFileName(path, distPath) {
383
+ let splitOnSlash = path.split('/');
384
+ splitOnSlash = splitOnSlash.filter(s => s !== '');
385
+ let lastPart = splitOnSlash[splitOnSlash.length-1];
386
+ let fileName = lastPart.split('.')[0];
387
+ if (fileName === 'index') fileName = splitOnSlash[splitOnSlash.length-2];
388
+ if (fileName === distPath) fileName = '/';
389
+ return fileName;
390
+ }
391
+
392
+ /**
393
+ * @description Return object with filename `name` and `extension`
394
+ * @param {path} - The file path (/path/to/file.ext)
395
+ * @returns {Object}
396
+ * @private
397
+ */
398
+ function getFileParts(path) {
399
+ if (!path) return;
400
+ const fileSplit = path.split('/');
401
+ const fileName = fileSplit[fileSplit.length - 1];
402
+ // If last split item is `index.html`, store its parent directory (if option to convert pages to directories is enabled)
403
+ // If not, there will be a lot of pages with `file.name` as
404
+ const fileNameIfIndex = !convertPageToDirectory.disabled && fileName === 'index.html' ? fileSplit[fileSplit.length - 2] : undefined;
405
+ const fileNameSplit = fileName.split('.');
406
+ return { name: fileNameSplit[0], nameIfIndex: fileNameIfIndex, ext: fileNameSplit[1] };
407
+ }
408
+
409
+ /**
410
+ * @description Return path to file without the file name and extension
411
+ * @param {path} - The file path (/path/to/file.ext)
412
+ * @returns {String}
413
+ * @private
414
+ */
415
+ function getFilePath(path) {
416
+ const pathSplit = path.split('/');
417
+ const filename = pathSplit.splice(pathSplit.length - 1, 1);
418
+ return pathSplit.join('/');
419
+ }
420
+
421
+ /**
422
+ * @description Recursively grab all paths in a folder structure
423
+ * @param {String} originalPath - The previous path
424
+ * @param {String} path - The new path to explore
425
+ * @param {RegExp} ignorePattern - A regex pattern to ignore certain files and folders
426
+ * @param {Array} paths - The on going list of paths found
427
+ * @returns {Array} - An array of paths
428
+ * @private
429
+ */
430
+ function getPaths(originalPath, path, ignorePattern, paths = []) {
431
+ try {
432
+ // Obtain a list of files and folders
433
+ const files = readdirSync(path);
434
+ files.forEach(file => {
435
+ const currentFilePath = `${path}/${file}`;
436
+ // Get the file descriptor
437
+ const fd = lstatSync(currentFilePath);
438
+ // If path is ignored, either by default or user-entered (`excludePaths` in /config/main.js),
439
+ // We won't do anything to it once it is copied to /dist
440
+ // This is handy for `/dist/assets/scripts/vendor`, for example, since that is code likely already minified
441
+ // and outside of the user's control
442
+ let allowed = true, pattern, match;
443
+ if (ignorePattern) {
444
+ ignorePattern.forEach(p => {
445
+ pattern = new RegExp(p, 'g');
446
+ match = currentFilePath.match(pattern);
447
+ if (match && match.length) allowed = false;
448
+ })
449
+ }
450
+ // Include file to use in build process
451
+ if (allowed) {
452
+ if (fd.isDirectory()) {
453
+ paths = [...paths, ...getPaths(originalPath, currentFilePath, ignorePattern)];
454
+ } else {
455
+ paths.push(currentFilePath);
456
+ }
457
+ }
458
+ });
459
+ return paths;
460
+ }
461
+ catch (err) { customError(err, `getPaths`); }
462
+ }
463
+
464
+ /**
465
+ * @description Return the correct selector for query select. Can either be a string,
466
+ * or an array of strings for multi-selector.
467
+ * @param {String|Array} attrs - The multiple selectors to query select off of
468
+ * @param {String} [el] - Optional element to add in front of attribute selector (Ex: `link[attr]` instead of `[attr]`)
469
+ * @returns {String}
470
+ * @private
471
+ */
472
+ function getSelector(attrs, el = '') {
473
+ let selector = '';
474
+ if (typeof attrs === 'string') selector = `${el}[${attrs}]`;
475
+ else attrs.forEach((a,i) => selector += i === 0 ? `${el}[${a}]` : `,${el}[${a}]`);
476
+ return selector;
477
+ }
478
+
479
+ /**
480
+ * @description Initializes a new Spinner and Timer instance on the executing scope (this)
481
+ * Note: Initialization must call the executing scope via `.call(this)`
482
+ * @example Util.initLogging.call(this)
483
+ * @private
484
+ */
485
+ function initLogging() {
486
+ this.loading = new Spinner();
487
+ this.timer = new Timer();
488
+ }
489
+
490
+ /**
491
+ * @description Check if path string has extension. Protects against directory names with `.` characters
492
+ * @property {String} str - Path string to test
493
+ * @returns {Boolean}
494
+ * @private
495
+ */
496
+ function hasExtension(str) {
497
+ const is2LengthExt = str[str.length - 3] === '.';
498
+ const is3LengthExt = str[str.length - 4] === '.';
499
+ const is4LengthExt = str[str.length - 5] === '.';
500
+ return is2LengthExt || is3LengthExt || is4LengthExt;
501
+ }
502
+
503
+ /**
504
+ * @description Pass in an 'opt-in' or 'opt-out' array to match current file against by extension type
505
+ * @param {Object} opts - The argument object
506
+ * @property {String} fileExt - The extension of the file
507
+ * @property {Object} [allowType] - The array of extensions to allow
508
+ * @property {String} [disallowType] - The array of extensions to disallow
509
+ * @returns {Boolean}
510
+ * @private
511
+ */
512
+ function isAllowedType({file,allowType,disallowType}) {
513
+ // Early Exit: No file name given
514
+ if (!file) return;
515
+ // Destructure properties
516
+ let {ext} = file;
517
+ // Early Exit: No valid extension
518
+ if (!ext) return false;
519
+ ext = ext.charAt(0) === '.' ? ext : `.${ext}`;
520
+ // If file extension NOT in allowed array, return false
521
+ if (allowType && allowType.indexOf(ext) === -1) return false;
522
+ // If file extension IS in disallowed array, return false
523
+ if (disallowType && disallowType.indexOf(ext) > -1) return false;
524
+ return true;
525
+ }
526
+
527
+ /**
528
+ * @description Return pattern match to `.html`
529
+ * @param {String} fileName - The target string
530
+ * @param {Array|String} target - The target extension(s) (html, js, etc.)
531
+ * @private
532
+ */
533
+ function isExtension(fileName, target) {
534
+ const isString = typeof target === 'string';
535
+ const ext = fileName.split('.').pop();
536
+ if (isString) return ext === target;
537
+ else return target.indexOf(ext) > -1;
538
+ }
539
+
540
+ /**
541
+ * @description Get a new JSDOM document/object from the passed in string source
542
+ * @docs https://github.com/jsdom/jsdom
543
+ * @param {Object} opts - The arguments object
544
+ * @property {String} fileSource - The source to make a traversable document from
545
+ * @property {Object} [options] - Optional JSDOM options config object
546
+ * @returns {Object}
547
+ */
548
+ function newJSDOM({src,options}) {
549
+ const opts = options || { url: jsdom.baseUrl };
550
+
551
+ // Protect <code-block> elements from JSDOM parsing.
552
+ // JSDOM treats custom elements as generic HTML and can mangle their
553
+ // text content (especially plain JS/CSS) into attribute-like tokens.
554
+ // We replace them with comment placeholders before parsing, then restore after.
555
+ const codeBlockStore = [];
556
+ const protectedSrc = src.replace(/<code-block\b[\s\S]*?<\/code-block>/gi, (match) => {
557
+ const index = codeBlockStore.length;
558
+ codeBlockStore.push(match);
559
+ return `<!--COOK_CB_${index}-->`;
560
+ });
561
+
562
+ const dom = new JSDOM(protectedSrc, opts);
563
+
564
+ // Attach the code-block store to the dom object so setSrc can restore them
565
+ if (codeBlockStore.length) {
566
+ dom._codeBlockStore = codeBlockStore;
567
+ }
568
+
569
+ return dom;
570
+ }
571
+
572
+ /**
573
+ * @description Get a new JSDOM fragment from the passed in string source
574
+ * @docs https://github.com/jsdom/jsdom
575
+ * @param {Object} opts - The arguments object
576
+ * @property {String} fileSource - The source to make a traversable document from
577
+ * @returns {Object}
578
+ */
579
+ function newFrag(src) {
580
+ return JSDOM.fragment(src);
581
+ }
582
+
583
+ /**
584
+ * @description Custom `Promise.all` that sends information to a callback fn when each promise is returned
585
+ * @param {Array} arr - The items to promisify and run method against
586
+ * @param {Function} method - The method to run against each promise item
587
+ * @param {Function} [cb] - Optional callback that passes returned infomation from the method for each promise that returns
588
+ * @param {Boolean} [pageLabel] - Optionally pass in the file or method name as a label for display in terminal if the promise rejects
589
+ * @returns {Object}
590
+ */
591
+ function promiseAll(arr, method, cb, pageLabel) {
592
+ const promises = arr.map(method);
593
+ if (cb) {
594
+ const length = promises.length;
595
+ for (const promise of promises) {
596
+ promise
597
+ .then(data => cb({length, data}))
598
+ .catch(err => customKill(`killed: ${err}${ ` in ${pageLabel}` || '' }`));
599
+ }
600
+ }
601
+ return Promise.all(promises);
602
+ }
603
+
604
+ /**
605
+ * @description Run method against target file asynchronously
606
+ * @param {Array} files - The array of file paths to modify
607
+ * @param {Function} method - The method to run against each file
608
+ */
609
+ async function runFileLoop(files, method) {
610
+ // Early Exit: No allowed files given
611
+ if (!files || !files.length) return;
612
+
613
+ // Is explicit logging enabled via environment flag?
614
+ const log = process.env.LOGGER;
615
+
616
+ // Show terminal message: Start
617
+ Logger.persist.header(`\nModify Files`);
618
+ // Start spinner message
619
+ const loading = new Spinner();
620
+ if (!log) loading.start(`Fetching allowed files`);
621
+ loading.total = files.length;
622
+
623
+ // Start timer
624
+ const timer = new Timer();
625
+ timer.start();
626
+
627
+ await recurseFiles(0);
628
+ async function recurseFiles(index) {
629
+ const file = files[index];
630
+ const fileName = file.path || file;
631
+ // For explicit logging, show file name in terminal
632
+ if (log) console.log(chalk.blue(fileName))
633
+ await method(file);
634
+ index += 1;
635
+ // For non-logging (default), update current page in-line in the terminal
636
+ if (!log) loading.updateAsPercentage(fileName, index, loading.total, true);
637
+ if (index < loading.total) await recurseFiles(index);
638
+ }
639
+
640
+ // End timer
641
+ if (log) console.log(chalk.gray('\n-----'));
642
+ loading.stop(`Files Modified (${loading.total}) ${timer.end()}`);
643
+ }
644
+
645
+ /**
646
+ * @description Get the correct DOM nodes as a string
647
+ * @param {*} param0
648
+ */
649
+ function setSrc({dom, path}) {
650
+ let result;
651
+
652
+ // Dom Fragment
653
+ if (!dom.window) {
654
+ const XMLSerializer = new JSDOM('').window.XMLSerializer;
655
+ const domString = new XMLSerializer().serializeToString(dom)
656
+ result = domString
657
+ .replace(/ xmlns="http:\/\/www.w3.org\/1999\/xhtml"/gmi, '')
658
+ .replace(/ns(\d)*?:(?:href)/gmi, 'href');
659
+ }
660
+ // Full HTML document
661
+ else {
662
+ const document = dom.window.document;
663
+ const isFullDoc = !!document.doctype;
664
+
665
+ if (isFullDoc) result = dom.serialize();
666
+ else result = `${document.head.innerHTML}${document.body.innerHTML}`;
667
+ }
668
+
669
+ // Restore protected <code-block> elements
670
+ if (dom._codeBlockStore) {
671
+ result = result.replace(/<!--COOK_CB_(\d+)-->/g, (_, i) => dom._codeBlockStore[i]);
672
+ }
673
+
674
+ return result;
675
+ }
676
+
677
+ /**
678
+ * @description Return dynamic value or 'skipped' if test failed
679
+ * @param {Array} test - Array to test
680
+ * @param {String} [label] - Optional label instead of 'skipped' default
681
+ * @returns {String}
682
+ */
683
+ function skipped(test, label = 'skipped') {
684
+ return test.length ? `(${test.length})` : chalk.grey('(skipped)');
685
+ }
686
+
687
+ /**
688
+ * @description Return whether dev live reload change event was an individual page change,
689
+ * AND if the file wasn't an include
690
+ * @param {Object} file
691
+ * @property {String} file.ext - The file's extension
692
+ * @property {String} file.name - The file's name
693
+ * @property {String} file.nameIfIndex - The file's name excluding `/index.html`
694
+ * @property {String} file.path - The file's full path
695
+ * @property {String} file.src - The file's source
696
+ * @private
697
+ */
698
+ async function updatePage(file) {
699
+ // Destructure object props
700
+ const {ext,path,src} = file;
701
+ // CREATE NEW DIRECTORY IN /DIST (If it doesn't exist)
702
+ // Note: Only for `.html` pages
703
+ if (ext === 'html') addDirectory(file);
704
+ // UPDATE FILE
705
+ await fs.writeFile(path, src);
706
+ }
707
+
708
+ /**
709
+ * @description Return whether dev live reload change event was an individual page change,
710
+ * AND if the file wasn't an include
711
+ */
712
+ function validatePageChange() {
713
+ // Page was changed when using localhost BrowserSync live reloading (`npm run dev`)
714
+ const changedDevPage = process.env.DEV_CHANGED_PAGE;
715
+ // Was the changed page an include file?
716
+ const isInclude = changedDevPage && !!changedDevPage.match(/\/(include)|(template)/);
717
+ // Return true (valid) if it was a page change AND it wasn't an include file
718
+ return changedDevPage && !isInclude;
719
+ }