fs: re-enable watch facility in AIX

On AIX, watch feature depends on AHAFS based Event infrastructure.
While in principle the watch use case is same across platforms, there
are subtle differences in the way AIX deals with this, with few
behavioral changes (external).

This commit addresses an assertion failure on folder watch, enabling the
AIX code for watch feature which was masked under a macro, open up
relevant test cases, skip tests which comes under the AIX limitation,
and make the document changes as appropriate.

Refs: #11094
Refs: #5085
PR-URL: #10085
Reviewed-By: Colin Ihrig <[email protected]>
Reviewed-By: Michael Dawson <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Sakthipriyan Vairamani <[email protected]>
Reviewed-By: Santiago Gimeno <[email protected]>

Author: gireeshpunathil

doc/api/fs.md

@@ -1752,6 +1752,13 @@ a new inode. The watch will emit an event for the delete but will continue
 watching the *original* inode. Events for the new inode will not be emitted.
 This is expected behavior.
 
+In AIX, save and close of a file being watched causes two notifications -
+one for adding new content, and one for truncation. Moreover, save and
+close operations on some platforms cause inode changes that force watch
+operations to become invalid and ineffective. AIX retains inode for the
+lifetime of a file, that way though this is different from Linux / OS X,
+this improves the usability of file watching. This is expected behavior.
+
 #### Filename Argument
 
 <!--type=misc-->

test/parallel/parallel.status

@@ -19,14 +19,7 @@ test-debug-signal-cluster         : PASS,FLAKY
 
 [$system==freebsd]
 
-# fs-watch currently needs special configuration on AIX and we
-# want to improve under https://github.com/nodejs/node/issues/5085.
-# Tests are disabled so CI can be green and we can spot other
-# regressions until this work is complete
 [$system==aix]
-test-fs-watch-enoent                 : FAIL, PASS
-test-fs-watch-encoding               : FAIL, PASS
-
 #covered by  https://github.com/nodejs/node/issues/3796
 # but more frequent on AIX ?
-test-debug-signal-cluster                : PASS, FLAKY
+test-debug-signal-cluster                : PASS, FLAKY

test/parallel/test-fs-watch-encoding.js

@@ -14,6 +14,15 @@ const common = require('../common');
 const fs = require('fs');
 const path = require('path');
 
+// fs-watch on folders have limited capability in AIX.
+// The testcase makes use of folder watching, and causes
+// hang. This behavior is documented. Skip this for AIX.
+
+if (common.isAix) {
+  common.skip('folder watch capability is limited in AIX.');
+  return;
+}
+
 common.refreshTmpDir();
 
 const fn = '新建文夹件.txt';