Added code and readme

Author: justingrant

LICENSE

@@ -1,21 +1,28 @@
-MIT License
+BSD 3-Clause License
 
 Copyright (c) 2022 js-temporal
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software without
+   specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -1,2 +1,65 @@
-# temporal-test262-runner
-Lightweight runner for ECMAScript Temporal's Test262 tests
+
+# Lightweight runner for ECMAScript Temporal's Test262 tests
+
+This package provides a fast way for polyfills of ECMAScript
+[`Temporal`](https://github.com/tc39/proposal-temporal) to run Temporal's 5,000+
+Test262 tests. Test262 (https://github.com/tc39/test262) is the official
+conformance test suite for ECMAScript, and this package quickly runs a subset of
+those tests that are specific to Temporal. All Temporal polyfills should pass
+Test262.
+
+This runner is much faster than
+[`test262-harness`](https://github.com/bterlson/test262-harness) (the default
+Test262 harness) because:
+* It runs only 5000+ Temporal-specific tests, instead of the full suite.
+* It pre-parses the Temporal polyfill into a
+  [`vm.Script`](https://nodejs.org/api/vm.html#class-vmscript), instead of
+  reading and parsing the whole file once for each test like the prelude option
+  of `test262-harness` does.
+
+For code coverage, set the environment variable `NODE_V8_COVERAGE` to the path
+(relative to the working directory) where coverage metrics should be output.
+These can be processed with the [`c8`](https://github.com/bcoe/c8) tool. NOTE:
+as of Node 18.7 there is a memory leak that makes it impossible to run the
+entire suite with NODE_V8_COVERAGE, so for code coverage tests you should run it
+in chunks.
+
+## Example Usage
+
+```js
+import runTest262 from 'temporal-test262-runner';
+
+const result = runTest262({
+  test262Dir: 'test262',
+  polyfillCodeFile: 'dist/script.js',
+  expectedFailureFiles: ['test/expected-failures.txt'],
+  testGlobs: process.argv.slice(2)
+});
+
+// if result is `true`, all tests succeeded
+process.exit(result ? 0 : 1);
+```
+
+## Options
+
+* `polyfillCodeFile: string` - Filename of the Temporal polyfill. Must
+  be a single ECMAScript file that contains the Temporal object injected into
+  the global namespace, as well as Temporal-related changes polyfilled into
+  `Intl` and `Date` built-in objects.
+* `test262Dir: string` - Root directory of the test262 submodule repo.
+* `testGlobs?: string[]` - If omitted, all tests will be run. This option
+  provides glob patterns that specify a subset of tests to be run. Example:
+  `[ 'PlainDateTime/**', 'prototype/with/*.js' ]` Globs are resolved relative
+  to `test/**∕Temporal/` subdirectories of `test262Dir`. If a pattern doesn't
+  match any files relative to `test/**∕Temporal/`, it will also try to match
+  relative to the current working directory, so that tab completion works.
+* `expectedFailureFiles?: string[]` Optional array of text filenames
+  that each contain a list of test files (relative to the `test` subdirectory
+  of `test262Dir`) that are expected to fail. Lines starting with `#` and
+  blank lines are ignored. Lines from multiple files will be concatenated and
+  de-duped. Example:
+  ```
+  # https://github.com/tc39/test262/pull/3548
+  built-ins/Temporal/Duration/compare/argument-string-negative-fractional-units.js
+  built-ins/Temporal/Duration/from/argument-string-negative-fractional-units.js
+  ```