lint: add rule to verify use of harness files

Verify that every test file which references a harness file using the
"includes" directive also contains at least one reference to a value
defined in the harness file.

To support this check, extend each harness file with a list of values
which it defines.

harness/arrayContains.js

@@ -3,6 +3,7 @@
 /*---
 description: |
     Verify that a subArray is contained within an array.
+defines: [arrayContains]
 ---*/
 
 /**

harness/assert.js

@@ -3,6 +3,7 @@
 /*---
 description: |
     Collection of assertion functions used throughout test262
+defines: [assert]
 ---*/
 
 

harness/assertRelativeDateMs.js

@@ -5,6 +5,7 @@ description: |
     Verify that the given date object's Number representation describes the
     correct number of milliseconds since the Unix epoch relative to the local
     time zone (as interpreted at the specified date).
+defines: [assertRelativeDateMs]
 ---*/
 
 /**

harness/async-gc.js

@@ -6,6 +6,7 @@ description: >
 features: [Symbol, async-functions]
 flags: [non-deterministic]
 features: [FinalizationGroup]
+defines: [asyncGC, asyncGCDeref, resolveAsyncGC]
 ---*/
 
 function asyncGC(...targets) {

harness/atomicsHelper.js

@@ -3,6 +3,11 @@
 /*---
 description: >
     Collection of functions used to interact with Atomics.* operations across agent boundaries.
+defines:
+  - $262.agent.getReport
+  - $262.agent.safeBroadcast
+  - $262.agent.tryYield
+  - $262.trySleep
 ---*/
 
 /**

harness/byteConversionValues.js

@@ -7,6 +7,7 @@ description: |
     This helper is mostly used on tests for TypedArray and DataView, and each
     array from the expected values must match the original values array on every
     index containing its original value.
+defines: [byteConversionValues]
 ---*/
 var byteConversionValues = {
   values: [

harness/compareArray.js

@@ -3,6 +3,7 @@
 /*---
 description: |
     Compare the contents of two arrays
+defines: [compareArray]
 ---*/
 
 // @ts-check

harness/compareIterator.js

@@ -2,6 +2,7 @@
 // This code is governed by the BSD license found in the LICENSE file.
 /*---
 description: Compare the values of an iterator with an array of expected values
+defines: [assert.compareIterator]
 ---*/
 
 // Example:

harness/dateConstants.js

@@ -3,6 +3,17 @@
 /*---
 description: |
     Collection of date-centric values
+defines:
+  - date_1899_end
+  - date_1900_start
+  - date_1969_end
+  - date_1970_start
+  - date_1999_end
+  - date_2000_start
+  - date_2099_end
+  - date_2100_start
+  - start_of_time
+  - end_of_time
 ---*/
 
 var date_1899_end = -2208988800001;

harness/decimalToHexString.js

@@ -3,6 +3,7 @@
 /*---
 description: |
     Collection of functions used to assert the correctness of various encoding operations.
+defines: [decimalToHexString, decimalToPercentHexString]
 ---*/
 
 function decimalToHexString(n) {

harness/deepEqual.js

@@ -3,6 +3,7 @@
 /*---
 description: |
     Compare two values structurally
+defines: [assert.deepEqual]
 ---*/
 
 // @ts-check

harness/detachArrayBuffer.js

@@ -5,7 +5,7 @@ description: |
     A function used in the process of asserting correctness of TypedArray objects.
 
     $262.detachArrayBuffer is defined by a host.
-
+defines: [$DETACHBUFFER]
 ---*/
 
 function $DETACHBUFFER(buffer) {

harness/doneprintHandle.js

@@ -2,7 +2,7 @@
 // This code is governed by the BSD license found in the LICENSE file.
 /*---
 description: |
-
+defines: [$DONE]
 ---*/
 
 function __consolePrintHandle__(msg) {

harness/fnGlobalObject.js

@@ -3,6 +3,7 @@
 /*---
 description: |
     Produce a reliable global object
+defines: [fnGlobalObject]
 ---*/
 
 var __globalObject = Function("return this;")();

harness/isConstructor.js

@@ -4,6 +4,7 @@
 /*---
 description: |
     Test if a given function is a constructor function.
+defines: [isConstructor]
 ---*/
 
 function isConstructor(f) {

harness/nans.js

@@ -6,6 +6,7 @@ description: |
     to create distinct bit representations on various platforms. These provide a
     weak basis for assertions regarding the consistent canonicalization of NaN
     values in Array buffers.
+defines: [NaNs]
 ---*/
 
 var NaNs = [

harness/nativeFunctionMatcher.js

@@ -8,7 +8,10 @@ info: |
 
     NativeFunction :
       function _IdentifierName_ opt ( _FormalParameters_ ) { [ native code ] }
-
+defines:
+  - NATIVE_FUNCTION_RE
+  - assertToStringOrNativeFunction
+  - assertNativeFunction
 ---*/
 const NATIVE_FUNCTION_RE = /\bfunction\b[\s\S]*\([\s\S]*\)[\s\S]*\{[\s\S]*\[[\s\S]*\bnative\b[\s\S]+\bcode\b[\s\S]*\][\s\S]*\}/;
 

harness/promiseHelper.js

@@ -6,6 +6,7 @@ description: |
     and incrementing by 1 for each entry in the array. Used by
     Promise tests to assert the order of execution in deep Promise
     resolution pipelines.
+defines: [checkSequence, checkSettledPromises]
 ---*/
 
 function checkSequence(arr, message) {

harness/propertyHelper.js

@@ -4,6 +4,15 @@
 description: |
     Collection of functions used to safely verify the correctness of
     property descriptors.
+defines:
+  - verifyProperty
+  - verifyEqualTo
+  - verifyWritable
+  - verifyNotWritable
+  - verifyEnumerable
+  - verifyNotEnumerable
+  - verifyConfigurable
+  - verifyNotConfigurable
 ---*/
 
 // @ts-check

harness/proxyTrapsHelper.js

@@ -4,6 +4,7 @@
 description: |
     Used to assert the correctness of object behavior in the presence
     and context of Proxy objects.
+defines: [allowProxyTraps]
 ---*/
 
 function allowProxyTraps(overrides) {

harness/regExpUtils.js

@@ -3,6 +3,7 @@
 /*---
 description: |
     Collection of functions used to assert the correctness of RegExp objects.
+defines: [buildString, testPropertyEscapes, matchValidator]
 ---*/
 
 function buildString({ loneCodePoints, ranges }) {

harness/sta.js

@@ -6,6 +6,7 @@ description: |
 
     - An error class to avoid false positives when testing for thrown exceptions
     - A function to explicitly throw an exception using the Test262Error class
+defines: [Test262Error, $ERROR, $DONOTEVALUATE]
 ---*/
 
 

harness/tcoHelper.js

@@ -5,6 +5,7 @@ description: |
     This defines the number of consecutive recursive function calls that must be
     made in order to prove that stack frames are properly destroyed according to
     ES2015 tail call optimization semantics.
+defines: [$MAX_ITERATIONS]
 ---*/
 
 

harness/testAtomics.js

@@ -3,6 +3,10 @@
 /*---
 description: |
     Collection of functions used to assert the correctness of SharedArrayBuffer objects.
+defines:
+  - testWithAtomicsOutOfBoundsIndices
+  - testWithAtomicsInBoundsIndices
+  - testWithAtomicsNonViewValues
 ---*/
 
 

harness/testBigIntTypedArray.js

@@ -3,6 +3,7 @@
 /*---
 description: |
     Collection of functions used to assert the correctness of BigInt TypedArray objects.
+defines: [TypedArray, testWithBigIntTypedArrayConstructors]
 ---*/
 
 /**

harness/testIntl.js

@@ -6,8 +6,24 @@ description: |
     This file contains shared functions for the tests in the conformance test
     suite for the ECMAScript Internationalization API.
 author: Norbert Lindenberg
+defines:
+  - testWithIntlConstructors
+  - taintDataProperty
+  - taintMethod
+  - taintProperties
+  - taintArray
+  - getLocaleSupportInfo
+  - getInvalidLanguageTags
+  - isCanonicalizedStructurallyValidLanguageTag
+  - getInvalidLocaleArguments
+  - testOption
+  - testForUnwantedRegExpChanges
+  - isValidNumberingSystem
+  - testNumberFormat
+  - getDateTimeComponents
+  - getDateTimeComponentValues
+  - isCanonicalizedStructurallyValidTimeZoneName
 ---*/
-
 /**
  */
 

harness/testTypedArray.js

@@ -3,6 +3,13 @@
 /*---
 description: |
     Collection of functions used to assert the correctness of TypedArray objects.
+defines:
+  - typedArrayConstructors
+  - floatArrayConstructors
+  - intArrayConstructors
+  - TypedArray
+  - testWithTypedArrayConstructors
+  - testTypedArrayConversions
 ---*/
 
 /**

harness/timer.js

@@ -3,6 +3,7 @@
 /*---
 description: |
     Used in website/scripts/sth.js
+defines: [setTimeout]
 ---*/
 //setTimeout is not available, hence this script was loaded
 if (Promise === undefined && this.setTimeout === undefined) {

harness/typeCoercion.js

@@ -4,6 +4,30 @@
 description: |
     Functions to help generate test cases for testing type coercion abstract
     operations like ToNumber.
+defines:
+  - testCoercibleToIndexZero
+  - testCoercibleToIndexOne
+  - testCoercibleToIndexFromIndex
+  - testCoercibleToIntegerZero
+  - testCoercibleToIntegerOne
+  - testCoercibleToNumberZero
+  - testCoercibleToNumberNan
+  - testCoercibleToNumberOne
+  - testCoercibleToIntegerFromInteger
+  - testPrimitiveWrappers
+  - testCoercibleToPrimitiveWithMethod
+  - testNotCoercibleToIndex
+  - testNotCoercibleToInteger
+  - testNotCoercibleToNumber
+  - testNotCoercibleToPrimitive
+  - testCoercibleToString
+  - testNotCoercibleToString
+  - testCoercibleToBooleanTrue
+  - testCoercibleToBooleanFalse
+  - testCoercibleToBigIntZero
+  - testCoercibleToBigIntOne
+  - testCoercibleToBigIntFromBigInt
+  - testNotCoercibleToBigInt
 ---*/
 
 function testCoercibleToIndexZero(test) {

harness/wellKnownIntrinsicObjects.js

@@ -3,6 +3,7 @@
 /*---
 description: |
     An Array of all representable Well-Known Intrinsic Objects
+defines: [WellKnownIntrinsicObjects]
 ---*/
 
 const WellKnownIntrinsicObjects = [

tools/lint/lib/checks/includes.py

@@ -0,0 +1,65 @@
+import os
+import re
+
+from ..check import Check
+from ..frontmatter import parse
+
+class CheckIncludes(Check):
+    '''Ensure tests make use of the harness files that they require via the
+    `includes` directive.'''
+    ID = 'INCLUDES'
+    _cache = dict()
+
+    @staticmethod
+    def _remove_frontmatter(source):
+        return re.sub(
+            r'/\*---.*---\*/', '', source, flags=re.DOTALL
+        )
+
+    @staticmethod
+    def _load(include_name):
+        if include_name not in CheckIncludes._cache:
+            with open(os.path.join('harness', include_name), 'r') as f:
+                source = f.read()
+
+            CheckIncludes._cache[include_name] = {
+                'name': include_name,
+                'source': CheckIncludes._remove_frontmatter(source),
+                'defines': parse(source)['defines']
+            }
+
+        return CheckIncludes._cache.get(include_name)
+
+    @staticmethod
+    def _has_reference(source, names):
+        for name in names:
+            if name in source:
+                return True
+        return False
+
+    def run(self, name, meta, source):
+        if not meta or 'includes' not in meta:
+            return
+
+        harness_files = [self._load(name) for name in meta['includes']]
+
+        if len(harness_files) == 0:
+            return 'If present, the `includes` tag must have at least one member'
+
+        without_frontmatter = self._remove_frontmatter(source)
+
+        for harness_file in harness_files:
+            if self._has_reference(without_frontmatter, harness_file['defines']):
+                continue
+
+            # If the test file does not reference a value defined by a given
+            # include file, inspect each of the other include files for such a
+            # reference.
+            for other_harness_file in harness_files:
+                if other_harness_file == harness_file:
+                    continue
+
+                if self._has_reference(other_harness_file['source'], harness_file['defines']):
+                    break
+            else:
+                return 'Unused include: "%s"' % harness_file['name']

tools/lint/lint.py

@@ -37,6 +37,7 @@ from lib.checks.features import CheckFeatures
 from lib.checks.frontmatter import CheckFrontmatter
 from lib.checks.harnessfeatures import CheckHarnessFeatures
 from lib.checks.harness import CheckHarness
+from lib.checks.includes import CheckIncludes
 from lib.checks.license import CheckLicense
 from lib.checks.negative import CheckNegative
 from lib.checks.filename import CheckFileName
@@ -61,6 +62,7 @@ checks = [
     CheckFeatures('features.txt'),
     CheckHarnessFeatures(),
     CheckHarness(),
+    CheckIncludes(),
     CheckLicense(),
     CheckNegative(),
     CheckNoPadding(),

tools/lint/test/fixtures/harness/usesDetachArrayBuffer.js

@@ -0,0 +1,13 @@
+// Copyright (C) 2019 Mike Pennisi.  All rights reserved.
+// This code is governed by the BSD license found in the LICENSE file.
+/*---
+description: |
+    A function used in the process of asserting correctness of TypedArray objects.
+
+    $262.detachArrayBuffer is defined by a host.
+defines: [modifiedDetachArrayBuffer]
+---*/
+
+function modifiedDetachArrayBuffer(buffer) {
+  return $DETACHBUFFER(buffer);
+}

tools/lint/test/fixtures/harness_features_valid.js

@@ -8,4 +8,4 @@ features: [TypedArray]
 includes: [testTypedArray.js]
 ---*/
 
-// empty
+intArrayConstructors;

tools/lint/test/fixtures/harness_verifyconfigurableproperty_invalid.js

@@ -5,7 +5,7 @@ HARNESS - verifyConfigurable & verifyProperty may not be used in the same file
 /*---
 esid: sec-whatever
 description: Minimal test
-includes: [verifyProperty.js]
+includes: [propertyHelper.js]
 ---*/
 
 verifyConfigurable(Object, '');

tools/lint/test/fixtures/harness_verifyconfigurableproperty_valid.js

@@ -4,7 +4,7 @@
 /*---
 esid: sec-whatever
 description: Minimal test
-includes: [verifyProperty.js]
+includes: [propertyHelper.js]
 ---*/
 
 verifyConfigurable(Object, '');

tools/lint/test/fixtures/includes_invalid_empty.js

@@ -0,0 +1,11 @@
+INCLUDES
+^ expected errors | v input
+// Copyright (C) 2019 Mike Pennisi. All rights reserved.
+// This code is governed by the BSD license found in the LICENSE file.
+/*---
+esid: sec-assignment-operators-static-semantics-early-errors
+description: Minimal test
+includes: []
+---*/
+
+void 0;

tools/lint/test/fixtures/includes_invalid_noref.js

@@ -0,0 +1,16 @@
+INCLUDES
+^ expected errors | v input
+// Copyright (C) 2019 Mike Pennisi. All rights reserved.
+// This code is governed by the BSD license found in the LICENSE file.
+/*---
+esid: sec-assignment-operators-static-semantics-early-errors
+description: Minimal test
+includes: [detachArrayBuffer.js]
+---*/
+
+// This file doesn't reference any names defined by the "include" file. It
+// contains some references that don't match exactly in order to verify that
+// the linter is not susceptible to false positives.
+DETACHBUFFER();
+$DETACHBUFFE();
+$DETACH_BUFFER();

tools/lint/test/fixtures/includes_valid_direct.js

@@ -0,0 +1,10 @@
+^ expected errors | v input
+// Copyright (C) 2019 Mike Pennisi. All rights reserved.
+// This code is governed by the BSD license found in the LICENSE file.
+/*---
+esid: sec-assignment-operators-static-semantics-early-errors
+description: Minimal test
+includes: [detachArrayBuffer.js]
+---*/
+
+$DETACHBUFFER();

tools/lint/test/fixtures/includes_valid_indirect.js

@@ -0,0 +1,13 @@
+^ expected errors | v input
+// Copyright (C) 2019 Mike Pennisi. All rights reserved.
+// This code is governed by the BSD license found in the LICENSE file.
+/*---
+esid: sec-assignment-operators-static-semantics-early-errors
+description: Minimal test
+includes: [detachArrayBuffer.js, usesDetachArrayBuffer.js]
+---*/
+
+// This file doesn't reference any names defined by the first "include" file,
+// but the second "include" file does.
+
+modifiedDetachArrayBuffer();