Refactor document.js and update canvas README line refs

Improved code formatting and readability in utils/document.js, including consistent spacing, function formatting, and directory creation safety. Updated line number references in wiki/docs/renderers/canvas/README.md to reflect changes in the source file.

Author: jonobr1

utils/document.js

@@ -4,18 +4,18 @@ var path = require('path');
 var compiler = require('jsdoc-api');
 var sourceFiles = require('./source-files');
 
-var pkg = JSON.parse(fs.readFileSync(
-  path.resolve(__dirname, '../package.json')));
+var pkg = JSON.parse(
+  fs.readFileSync(path.resolve(__dirname, '../package.json'))
+);
 var directory = [];
 
 var template = _.template(
-  fs.readFileSync(
-    path.resolve(__dirname, './docs.template'),
-    { encoding: 'utf8' }
-  )
+  fs.readFileSync(path.resolve(__dirname, './docs.template'), {
+    encoding: 'utf8',
+  })
 );
 
-pkg.template = function(str) {
+pkg.template = function (str) {
   if (typeof str === 'string') {
     var regex = /\$\w*/g;
     var match = str.match(regex);
@@ -30,58 +30,52 @@ pkg.template = function(str) {
 preprocess();
 
 function preprocess() {
-
-  _.each(sourceFiles, function(file) {
-
+  _.each(sourceFiles, function (file) {
     var sourceFile = path.resolve(__dirname, '../', file);
-    var pivotDir = ['/docs/', file.replace('jsm/', '')
-      .replace('src/', '').replace('.js', '/')].join('');
+    var pivotDir = [
+      '/docs/',
+      file.replace('jsm/', '').replace('src/', '').replace('.js', '/'),
+    ].join('');
 
     var citations = compiler.explainSync({
       files: sourceFile,
-      cache: false
+      cache: false,
     });
 
     var root = getRoot(citations);
 
     directory.push({ name: root.longname, dir: pivotDir });
-
   });
 
   process();
-
 }
 
 function process() {
-
-  _.each(sourceFiles, function(file) {
-
+  _.each(sourceFiles, function (file) {
     var sourceFile = path.resolve(__dirname, '../', file);
-    var pivotDir = ['/docs/', file.replace('jsm/', '')
-      .replace('src/', '').replace('.js', '/')].join('');
+    var pivotDir = [
+      '/docs/',
+      file.replace('jsm/', '').replace('src/', '').replace('.js', '/'),
+    ].join('');
 
     var outputDir = path.resolve(__dirname, '../wiki' + pivotDir);
     var outputFile = path.join(outputDir, '/README.md');
 
     var citations = compiler.explainSync({
       files: sourceFile,
-      cache: false
+      cache: false,
     });
 
-    citations.slice(0).forEach(function(object) {
-
+    citations.slice(0).forEach(function (object) {
       var a = object.undocumented;
       var b = /package:undefined/i.test(object.longname);
       var c = /Two\.Utils\.Events\.(bind|unbind)/i.test(object.memberof);
       var d = /(private|protected)/i.test(object.access);
 
       if (a || b || c || d) {
-
         // Remove private / hidden / incomplete documented citations
         citations.splice(citations.indexOf(object), 1);
-
       } else {
-
         expandLink(object, 'description');
         _.each(object.params, expandParam, object);
         _.each(object.returns, expandParam, object);
@@ -90,11 +84,11 @@ function process() {
         object.see = _.map(object.see, expandSee, object);
 
         var sn;
-        sn = object.longname.replace(/#/ig, '.');
+        sn = object.longname.replace(/#/gi, '.');
         var snList = sn.split('.');
-        var snIndex = (snList.length > 2) ? 2 : 1;
+        var snIndex = snList.length > 2 ? 2 : 1;
         object.shortname = snList.slice(snIndex).join('.');
-        object.prefixname = sn.replace(object.shortname, "");
+        object.prefixname = sn.replace(object.shortname, '');
 
         // name and href for augments property
         var an;
@@ -108,17 +102,15 @@ function process() {
         if (an) {
           object.augmentsHref = getHref(an.slice(1).join('.'));
         }
-
       }
-
     });
 
     var citationsByScope = {
       instance: [],
-      static: []
+      static: [],
     };
 
-    _.each(citations, function(citation) {
+    _.each(citations, function (citation) {
       if (/#/i.test(citation.longname)) {
         citationsByScope.instance.push(citation);
       } else {
@@ -137,33 +129,43 @@ function process() {
     //   })
     // );
 
-    fs.mkdirSync(outputDir + '/', { recursive: true });
-    fs.writeFileSync(outputFile.replace('README.md', 'docs.json'),
-      JSON.stringify(citations));
+    // Ensure outputDir is inside the project root
+    var projectRoot = path.resolve(__dirname, '../');
+    var relative = path.relative(projectRoot, outputDir);
 
-    fs.writeFileSync(outputFile, template({
-      root: getRoot(citations, true),
-      citations: citations,
-      package: pkg
-    }));
+    if (relative && !relative.startsWith('..') && !path.isAbsolute(relative)) {
+      fs.mkdirSync(outputDir, { recursive: true });
+    } else {
+      throw new Error(
+        'Refusing to create output directory outside project root: ' + outputDir
+      );
+    }
+    fs.writeFileSync(
+      outputFile.replace('README.md', 'docs.json'),
+      JSON.stringify(citations)
+    );
+
+    fs.writeFileSync(
+      outputFile,
+      template({
+        root: getRoot(citations, true),
+        citations: citations,
+        package: pkg,
+      })
+    );
 
     console.log('Generated', outputFile);
-
   });
-
 }
 
 function getHref(name) {
-
   name = name.toLowerCase();
 
   for (var i = 0; i < sourceFiles.length; i++) {
-
     var sf = sourceFiles[i];
     if (sf.includes(name)) {
       return transform(sf);
     }
-
   }
 
   return null;
@@ -172,11 +174,8 @@ function getHref(name) {
     var path = str.replace('src/', '').replace('jsm/', '').replace('.js', '');
     return `/docs/${path}/`;
   }
-
 }
 
-
-
 function getRoot(citations, shouldSplice) {
   var list = citations.slice(0);
   for (var i = 0; i < list.length; i++) {
@@ -214,26 +213,20 @@ function expandParam(param) {
 }
 
 function expandLink(object, property) {
-
   var value = object[property];
   var shouldRecurse = false;
 
   if (value) {
-
     var regex = /\{@link ([\w\d:/?\-.#]*)\}/i;
     var link = value.match(regex);
 
     if (link && link.length > 1) {
-
       var name = link[1];
 
       if (/http/i.test(name)) {
-
         object[property] = value.replace(regex, '[$1]($1)');
         shouldRecurse = true;
-
       } else {
-
         var fragments = name.split(/[.#]/i);
         var longname = name.replace(/#/i, '.');
 
@@ -250,24 +243,20 @@ function expandLink(object, property) {
           '(',
           dir,
           hash ? '#' + hash.toLowerCase() : '',
-          ')'
+          ')',
         ].join('');
 
         object[property] = value.replace(regex, href);
         shouldRecurse = true;
-
       }
-
     }
-
   }
 
   if (shouldRecurse) {
     expandLink(object, property);
   }
 
   return object;
-
 }
 
 function getDirectoryMatch(str) {

wiki/docs/renderers/canvas/README.md

@@ -71,8 +71,8 @@ A massive object filled with utility functions and properties to render Two.js o
 
 <div class="meta">
 
-  <a class="lineno" target="_blank" rel="noopener noreferrer" href="https://github.com/jonobr1/two.js/blob/main/src/renderers/canvas.js#L1123">
-    canvas.js:1123
+  <a class="lineno" target="_blank" rel="noopener noreferrer" href="https://github.com/jonobr1/two.js/blob/main/src/renderers/canvas.js#L1128">
+    canvas.js:1128
   </a>
 
 </div>
@@ -118,8 +118,8 @@ The `<canvas />` associated with the Two.js scene.
 
 <div class="meta">
 
-  <a class="lineno" target="_blank" rel="noopener noreferrer" href="https://github.com/jonobr1/two.js/blob/main/src/renderers/canvas.js#L1092">
-    canvas.js:1092
+  <a class="lineno" target="_blank" rel="noopener noreferrer" href="https://github.com/jonobr1/two.js/blob/main/src/renderers/canvas.js#L1097">
+    canvas.js:1097
   </a>
 
 </div>
@@ -165,8 +165,8 @@ Associated two dimensional context to render on the `<canvas />`.
 
 <div class="meta">
 
-  <a class="lineno" target="_blank" rel="noopener noreferrer" href="https://github.com/jonobr1/two.js/blob/main/src/renderers/canvas.js#L1098">
-    canvas.js:1098
+  <a class="lineno" target="_blank" rel="noopener noreferrer" href="https://github.com/jonobr1/two.js/blob/main/src/renderers/canvas.js#L1103">
+    canvas.js:1103
   </a>
 
 </div>
@@ -212,8 +212,8 @@ Determines whether the canvas clears the background each draw call.
 
 <div class="meta">
 
-  <a class="lineno" target="_blank" rel="noopener noreferrer" href="https://github.com/jonobr1/two.js/blob/main/src/renderers/canvas.js#L1104">
-    canvas.js:1104
+  <a class="lineno" target="_blank" rel="noopener noreferrer" href="https://github.com/jonobr1/two.js/blob/main/src/renderers/canvas.js#L1109">
+    canvas.js:1109
   </a>
 
 </div>
@@ -259,8 +259,8 @@ The root group of the scenegraph.
 
 <div class="meta">
 
-  <a class="lineno" target="_blank" rel="noopener noreferrer" href="https://github.com/jonobr1/two.js/blob/main/src/renderers/canvas.js#L1115">
-    canvas.js:1115
+  <a class="lineno" target="_blank" rel="noopener noreferrer" href="https://github.com/jonobr1/two.js/blob/main/src/renderers/canvas.js#L1120">
+    canvas.js:1120
   </a>
 
 </div>
@@ -321,8 +321,8 @@ Change the size of the renderer.
 
 <div class="meta">
 
-  <a class="lineno" target="_blank" rel="noopener noreferrer" href="https://github.com/jonobr1/two.js/blob/main/src/renderers/canvas.js#L1129">
-    canvas.js:1129
+  <a class="lineno" target="_blank" rel="noopener noreferrer" href="https://github.com/jonobr1/two.js/blob/main/src/renderers/canvas.js#L1134">
+    canvas.js:1134
   </a>
 
 </div>
@@ -366,8 +366,8 @@ Render the current scene to the `<canvas />`.
 
 <div class="meta">
 
-  <a class="lineno" target="_blank" rel="noopener noreferrer" href="https://github.com/jonobr1/two.js/blob/main/src/renderers/canvas.js#L1157">
-    canvas.js:1157
+  <a class="lineno" target="_blank" rel="noopener noreferrer" href="https://github.com/jonobr1/two.js/blob/main/src/renderers/canvas.js#L1162">
+    canvas.js:1162
   </a>
 
 </div>