Added @internal Js comments to internal API functions

Created ESLint rule to check whether internal API functions are properly annotated or not
Added support to get list of puvlic API functions (map.json created during linting)

Signed-off-by: Naveen Jain <[email protected]>

Author: nveenjain

package.json

@@ -28,7 +28,9 @@
     "test:ci": "yarn check --integrity && npm run prettier:check && npm run lint -- --no-cache && npm run check && npm run testonly:cover && npm run check:ts && npm run check:spelling && npm run build",
     "testonly": "mocha --full-trace src/**/__tests__/**/*-test.js",
     "testonly:cover": "nyc npm run testonly",
-    "lint": "eslint --rulesdir './resources/eslint-rules' --rule 'no-dir-import: error' --cache --ext .js,.ts src resources",
+    "prelint": "node resources/generate-exported",
+    "lint": "eslint --rulesdir './resources/eslint-rules' --rule 'no-dir-import: error' --cache --ext .js,.ts src resources && eslint --rulesdir ./resources/eslint-rules/ --rule 'internal-func: 1'  src",
+    "postlint": "rm resources/babel-plugins/map.json",
     "benchmark": "node --noconcurrent_sweeping --expose-gc --predictable ./resources/benchmark.js",
     "prettier": "prettier --ignore-path .gitignore --write --list-different \"**/*.{js,ts,md,json,yml}\"",
     "prettier:check": "prettier --ignore-path .gitignore --check \"**/*.{js,ts,md,json,yml}\"",

resources/babel-plugins/extract-exports.js

@@ -0,0 +1,117 @@
+// @flow strict
+
+'use strict';
+
+// @noflow
+
+const path = require('path');
+const fs = require('fs');
+
+const { HashMap } = require('./helper');
+
+// Create a new Hashmap to store file names and declarations
+const mp = new HashMap();
+
+// All the rules that are required by plugin
+const ExportNamedDeclaration = {
+  enter(babelPath, state) {
+    if (babelPath.node.declaration) {
+      return handleDeclaration(babelPath, state);
+    }
+
+    if (babelPath.node.specifiers) {
+      return handleNodeSpecifiers(
+        babelPath.node.specifiers,
+        state,
+        babelPath.node.source ? babelPath.node.source.value : undefined,
+      );
+    }
+  },
+};
+
+const ExportAllDeclaration = {
+  enter(babelPath, state) {
+    mp.add(
+      '*',
+      state,
+      babelPath.node.source ? babelPath.node.source.value : undefined,
+    );
+  },
+};
+
+module.exports = function() {
+  return {
+    visitor: {
+      ExportNamedDeclaration,
+      ExportAllDeclaration,
+      ExportDefaultDeclaration: ExportNamedDeclaration,
+      Program: {
+        exit() {
+          return writeToJSON();
+        },
+      },
+    },
+  };
+};
+
+// Helper functions for the rules
+function handleDeclaration(babelPath, state) {
+  switch (babelPath.node.declaration.type) {
+    case 'VariableDeclaration':
+      return handleVariableDeclarations(
+        babelPath.node.declaration,
+        state,
+        babelPath.node.source ? babelPath.node.source.value : undefined,
+      );
+    case 'FunctionDeclaration':
+    case 'ClassDeclaration':
+      return handleFunctionDeclarations(
+        babelPath.node.declaration,
+        state,
+        babelPath.node.source ? babelPath.node.source.value : undefined,
+      );
+  }
+}
+
+function handleNodeSpecifiers(specifiers, state, source) {
+  return specifiers.forEach(specifier => {
+    switch (specifier.type) {
+      case 'ExportSpecifier':
+        mp.add(specifier.local.name, state, source);
+        break;
+      case 'ExportNamespaceSpecifier':
+        mp.add('*', state, source);
+        break;
+    }
+  });
+}
+
+function handleVariableDeclarations(variableDeclaration, state, source) {
+  variableDeclaration.declarations.forEach(declaration =>
+    mp.add(declaration.id.name, state, source),
+  );
+}
+
+function handleFunctionDeclarations(declaration, state, source) {
+  return mp.add(declaration.id.name, state, source);
+}
+
+// To write final result to JSON file
+function writeToJSON() {
+  if (!fs.existsSync(path.join(__dirname, '/map.json'))) {
+    fs.writeFileSync(path.join(__dirname, '/map.json'), JSON.stringify({}));
+  }
+  const exportedValues = require(path.join(__dirname, '/map.json'));
+  for (const key of mp.keys()) {
+    exportedValues[key] = exportedValues[key] || [];
+
+    exportedValues[key] = exportedValues[key].concat(Array.from(mp.get(key)));
+
+    exportedValues[key] = Array.from(new Set(exportedValues[key]));
+  }
+
+  fs.writeFileSync(
+    path.join(__dirname, '/map.json'),
+    JSON.stringify(exportedValues),
+  );
+}

resources/babel-plugins/helper/index.js

@@ -0,0 +1,33 @@
+// @flow strict
+
+'use strict';
+const path = require('path');
+
+class HashMap {
+  constructor() {
+    this._map = new Map();
+  }
+
+  add(value, state, source) {
+    let filepath = path.resolve(state.file.opts.filename);
+    if (source) {
+      const pathArray = state.file.opts.filename.split('/');
+      const directoryPath = pathArray.slice(0, pathArray.length - 1).join('/');
+      filepath = require.resolve(path.resolve(directoryPath, source));
+    }
+    if (!this._map.has(filepath)) {
+      this._map.set(filepath, new Set());
+    }
+    this._map.get(filepath).add(value);
+  }
+
+  get(key) {
+    return this._map.get(key);
+  }
+
+  keys() {
+    return this._map.keys();
+  }
+}
+
+module.exports = { HashMap };

resources/eslint-rules/internal-func.js

@@ -0,0 +1,49 @@
+// @flow strict
+
+// @noflow
+
+'use strict';
+const path = require('path');
+
+const listOfExports = require(path.join(
+  process.cwd(),
+  '/resources/babel-plugins/',
+  'map.json',
+));
+module.exports = {
+  create(context) {
+    function isExportedLocallyOnly(name) {
+      if (!listOfExports[context.getFilename()]) {
+        return true;
+      }
+      return !listOfExports[context.getFilename()].find(
+        value => value === name || value === '*',
+      );
+    }
+
+    const source = context.getSourceCode();
+    /**
+     *
+     */
+    return {
+      'ExportNamedDeclaration > :matches(FunctionDeclaration,ClassDeclaration)'(
+        node,
+      ) {
+        if (isExportedLocallyOnly(node.id.name)) {
+          if (!source.getJSDocComment(node)) {
+            return context.report({
+              node,
+              message: 'Please enter JSDoC internal functions using @internal',
+            });
+          }
+          if (!source.getJSDocComment(node).value.includes('@internal')) {
+            context.report({
+              node,
+              message: 'Please annotate internal functions using @internal',
+            });
+          }
+        }
+      },
+    };
+  },
+};

resources/generate-exported.js

@@ -0,0 +1,26 @@
+// @noflow
+
+'use strict';
+
+const babel = require('@babel/core');
+const flowTypesPlugin = require('@babel/plugin-transform-flow-strip-types');
+
+const extractExportPlugin = require('./babel-plugins/extract-exports');
+
+const directoriesToScan = [
+  '/src',
+  '/src/error',
+  '/src/type',
+  '/src/language',
+  '/src/validation',
+  '/src/utilities',
+  '/src/execution',
+  '/src/subscription',
+];
+
+directoriesToScan.forEach(path =>
+  babel.transformFileSync(process.cwd() + path + '/index.js', {
+    babelrc: false,
+    plugins: [flowTypesPlugin, extractExportPlugin],
+  }),
+);

src/__tests__/starWarsData.js

@@ -122,6 +122,7 @@ function getCharacter(id) {
 
 /**
  * Allows us to query for a character's friends.
+ * @internal
  */
 export function getFriends(character: Character): Array<Promise<Character>> {
   // Notice that GraphQL accepts Arrays of Promises.
@@ -130,6 +131,7 @@ export function getFriends(character: Character): Array<Promise<Character>> {
 
 /**
  * Allows us to fetch the undisputed hero of the Star Wars trilogy, R2-D2.
+ * @internal
  */
 export function getHero(episode: number): Character {
   if (episode === 5) {
@@ -142,13 +144,15 @@ export function getHero(episode: number): Character {
 
 /**
  * Allows us to query for the human with the given id.
+ * @internal
  */
 export function getHuman(id: string): Human {
   return humanData[id];
 }
 
 /**
  * Allows us to query for the droid with the given id.
+ * @internal
  */
 export function getDroid(id: string): Droid {
   return droidData[id];

src/jsutils/Path.js

@@ -7,6 +7,7 @@ export type Path = {|
 
 /**
  * Given a Path and a key, return a new Path containing the new key.
+ * @internal
  */
 export function addPath(
   prev: $ReadOnly<Path> | void,

src/language/__tests__/parser-benchmark.js

@@ -6,6 +6,9 @@ import { kitchenSinkQuery } from '../../__fixtures__/index';
 
 export const name = 'Parse kitchen sink';
 export const count = 1000;
+/**
+ * @internal
+ */
 export function measure() {
   parse(kitchenSinkQuery);
 }

src/language/ast.js

@@ -8,6 +8,7 @@ import { type TokenKindEnum } from './tokenKind';
 /**
  * Contains a range of UTF-8 character offsets and token references that
  * identify the region of the source from which the AST derived.
+ * @internal
  */
 export class Location {
   /**
@@ -52,6 +53,7 @@ defineToJSON(Location, function() {
 /**
  * Represents a range of characters represented by a lexical token
  * within a Source.
+ * @internal
  */
 export class Token {
   /**

src/utilities/__tests__/buildASTSchema-benchmark.js

@@ -10,6 +10,9 @@ const schemaAST = parse(bigSchemaSDL);
 
 export const name = 'Build Schema from AST';
 export const count = 10;
+/**
+ * @internal
+ */
 export function measure() {
   buildASTSchema(schemaAST, { assumeValid: true });
 }

src/utilities/__tests__/buildClientSchema-benchmark.js

@@ -6,6 +6,9 @@ import { bigSchemaIntrospectionResult } from '../../__fixtures__/index';
 
 export const name = 'Build Schema from Introspection';
 export const count = 10;
+/**
+ * @internal
+ */
 export function measure() {
   buildClientSchema(bigSchemaIntrospectionResult.data, { assumeValid: true });
 }

src/utilities/__tests__/introspectionFromSchema-benchmark.js

@@ -13,6 +13,9 @@ const document = parse(getIntrospectionQuery());
 
 export const name = 'Execute Introspection Query';
 export const count = 10;
+/**
+ * @internal
+ */
 export function measure() {
   execute({ schema, document });
 }

src/validation/ValidationContext.js

@@ -38,6 +38,7 @@ type VariableUsage = {|
  * An instance of this class is passed as the "this" context to all validators,
  * allowing access to commonly useful contextual information from within a
  * validation rule.
+ * @internal
  */
 export class ASTValidationContext {
   _ast: DocumentNode;
@@ -133,6 +134,9 @@ export class ASTValidationContext {
 
 export type ASTValidationRule = ASTValidationContext => ASTVisitor;
 
+/**
+ * @internal
+ */
 export class SDLValidationContext extends ASTValidationContext {
   _schema: ?GraphQLSchema;
 

src/validation/__tests__/harness.js

@@ -397,6 +397,9 @@ export const testSchema = new GraphQLSchema({
   ],
 });
 
+/**
+ * @internal
+ */
 export function expectValidationErrorsWithSchema(
   schema: GraphQLSchema,
   rule: ValidationRule,
@@ -407,10 +410,16 @@ export function expectValidationErrorsWithSchema(
   return expect(errors);
 }
 
+/**
+ * @internal
+ */
 export function expectValidationErrors(rule: ValidationRule, queryStr: string) {
   return expectValidationErrorsWithSchema(testSchema, rule, queryStr);
 }
 
+/**
+ * @internal
+ */
 export function expectSDLValidationErrors(
   schema: ?GraphQLSchema,
   rule: SDLValidationRule,

src/validation/__tests__/validateGQL-benchmark.js

@@ -13,6 +13,9 @@ const queryAST = parse(getIntrospectionQuery());
 
 export const name = 'Validate Introspection Query';
 export const count = 50;
+/**
+ * @internal
+ */
 export function measure() {
   validate(schema, queryAST);
 }