doc,tools: allow stability table to be updated

Keep markers for the stability table so that it can be updated on subsequent runs of the doc tooling. Only overwrite the files if they have been changed. PR-URL: #38048 Fixes: #37886 Reviewed-By: Antoine du Hamel <[email protected]> Reviewed-By: Rich Trott <[email protected]> Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Juan José Arboleda <[email protected]>
nodejs · May 1, 2021 · 4043275 · 4043275
1 parent 8615fa1
commit 4043275
Show file tree

Hide file tree

Showing 2 changed files with 18 additions and 14 deletions.
diff --git a/doc/api/documentation.md b/doc/api/documentation.md
@@ -50,7 +50,8 @@ modifications occur. To avoid surprises, use of an Experimental feature may need
 a command-line flag. Experimental features may also emit a [warning][].
 
 ## Stability overview
-<!-- STABILITY_OVERVIEW_SLOT -->
+<!-- STABILITY_OVERVIEW_SLOT_BEGIN -->
+<!-- STABILITY_OVERVIEW_SLOT_END -->
 
 ## JSON output
 <!-- YAML

diff --git a/tools/doc/stability.js b/tools/doc/stability.js
@@ -14,7 +14,9 @@ const visit = require('unist-util-visit');
 
 const source = `${__dirname}/../../out/doc/api`;
 const data = require(path.join(source, 'all.json'));
-const mark = '<!-- STABILITY_OVERVIEW_SLOT -->';
+const markBegin = '<!-- STABILITY_OVERVIEW_SLOT_BEGIN -->';
+const markEnd = '<!-- STABILITY_OVERVIEW_SLOT_END -->';
+const mark = `${markBegin}(.*)${markEnd}`;
 
 const output = {
   json: path.join(source, 'stability.json'),
@@ -84,28 +86,29 @@ function processStability() {
 
 function updateStabilityMark(file, value, mark) {
   const fd = fs.openSync(file, 'r+');
-  const content = fs.readFileSync(fd);
+  const content = fs.readFileSync(fd, { encoding: 'utf8' });
 
-  // Find the position of the `mark`.
-  const index = content.indexOf(mark);
-
-  // Overwrite the mark with `value` parameter.
-  const offset = fs.writeSync(fd, value, index, 'utf-8');
-
-  // Re-write the end of the file after `value`.
-  fs.writeSync(fd, content, index + mark.length, undefined, index + offset);
+  const replaced = content.replace(mark, value);
+  if (replaced !== content) {
+    fs.writeSync(fd, replaced, 0, 'utf8');
+  }
   fs.closeSync(fd);
 }
 
 const stability = collectStability(data);
 
 // add markdown
 const markdownTable = createMarkdownTable(stability);
-updateStabilityMark(output.docMarkdown, markdownTable, mark);
+updateStabilityMark(output.docMarkdown,
+                    `${markBegin}\n${markdownTable}\n${markEnd}`,
+                    new RegExp(mark, 's'));
 
 // add html table
 const html = createHTML(markdownTable);
-updateStabilityMark(output.docHTML, html, mark);
+updateStabilityMark(output.docHTML, `${markBegin}${html}${markEnd}`,
+                    new RegExp(mark, 's'));
 
 // add json output
-updateStabilityMark(output.docJSON, JSON.stringify(html), JSON.stringify(mark));
+updateStabilityMark(output.docJSON,
+                    JSON.stringify(`${markBegin}${html}${markEnd}`),
+                    new RegExp(JSON.stringify(mark), 's'));