Merge branch 'master' of https://github.com/microsoft/TypeScript

Author: rhillefeld

.dockerignore

@@ -43,7 +43,6 @@ yarn-error.log
 .parallelperf.*
 .failed-tests
 TEST-results.xml
-package-lock.json
 tests
 .vscode
 .git

.github/codeql/codeql-configuration.yml

@@ -0,0 +1,4 @@
+name : CodeQL Configuration
+
+paths:
+  - './src' 

.github/workflows/ci.yml

@@ -30,8 +30,7 @@ jobs:
       run: |
         npm uninstall typescript --no-save
         npm uninstall tslint --no-save
-    - run:  npm install
-    - run:  npm update
+    - run:  npm ci
 
     # Re: https://github.com/actions/setup-node/pull/125
     - name: Register Problem Matcher for TSC
@@ -45,4 +44,4 @@ jobs:
 
     - name: Validate the browser can import TypeScript
       run: gulp test-browser-integration
-    
+

.github/workflows/codeql.yml

@@ -0,0 +1,54 @@
+name: "Code scanning - action"
+
+on:
+  push:
+  pull_request:
+  schedule:
+    - cron: '0 19 * * 0'
+
+jobs:
+  CodeQL-Build:
+
+    # CodeQL runs on ubuntu-latest and windows-latest
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v2
+      with:
+        # We must fetch at least the immediate parents so that if this is
+        # a pull request then we can checkout the head.
+        fetch-depth: 2
+
+    # If this run was triggered by a pull request event, then checkout
+    # the head of the pull request instead of the merge commit.
+    - run: git checkout HEAD^2
+      if: ${{ github.event_name == 'pull_request' }}
+      
+    # Initializes the CodeQL tools for scanning.
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v1
+      with:
+        config-file: ./.github/codeql/codeql-configuration.yml
+      # Override language selection by uncommenting this and choosing your languages
+      # with:
+      #   languages: go, javascript, csharp, python, cpp, java
+
+    # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
+    # If this step fails, then you should remove it and run the build manually (see below)
+    - name: Autobuild
+      uses: github/codeql-action/autobuild@v1
+
+    # ℹ️ Command-line programs to run using the OS shell.
+    # 📚 https://git.io/JvXDl
+
+    # ✏️ If the Autobuild fails above, remove it and uncomment the following three lines
+    #    and modify them (or add more) to build your code if your project
+    #    uses a compiled language
+
+    #- run: |
+    #   make bootstrap
+    #   make release
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v1

.github/workflows/new-release-branch.yaml

@@ -23,7 +23,7 @@ jobs:
         sed -i -e 's/const versionMajorMinor = ".*"/const versionMajorMinor = "${{ github.event.client_payload.core_major_minor }}"/g' tests/baselines/reference/api/typescript.d.ts
         sed -i -e 's/const versionMajorMinor = ".*"/const versionMajorMinor = "${{ github.event.client_payload.core_major_minor }}"/g' tests/baselines/reference/api/tsserverlibrary.d.ts
         sed -i -e 's/const version = `${versionMajorMinor}.0-.*`/const version = `${versionMajorMinor}.0-${{ github.event.client_payload.core_tag || 'dev' }}`/g' src/compiler/corePublic.ts
-        npm install
+        npm ci
         gulp LKG
         npm test
         git diff
@@ -32,7 +32,7 @@ jobs:
         git add tests/baselines/reference/api/typescript.d.ts
         git add tests/baselines/reference/api/tsserverlibrary.d.ts
         git add ./lib
-        git config user.email "ts_bot@rcavanaugh.com"
+        git config user.email "typescriptbot@microsoft.com"
         git config user.name "TypeScript Bot"
         git commit -m 'Bump version to ${{ github.event.client_payload.package_version }} and LKG'
         git push --set-upstream origin ${{ github.event.client_payload.branch_name }}

.github/workflows/release-branch-artifact.yaml

@@ -21,8 +21,7 @@ jobs:
         npm uninstall tslint --no-save
     - name: npm install and test
       run: |
-        npm install
-        npm update
+        npm ci
         npm test
       env:
         CI: true
@@ -41,4 +40,3 @@ jobs:
       with:
         name: tgz
         path: typescript.tgz
-    

.github/workflows/set-version.yaml

@@ -29,7 +29,7 @@ jobs:
         sed -i -e 's/const versionMajorMinor = ".*"/const versionMajorMinor = "${{ github.event.client_payload.core_major_minor }}"/g' tests/baselines/reference/api/typescript.d.ts
         sed -i -e 's/const versionMajorMinor = ".*"/const versionMajorMinor = "${{ github.event.client_payload.core_major_minor }}"/g' tests/baselines/reference/api/tsserverlibrary.d.ts
         sed -i -e 's/const version = .*;/const version = "${{ github.event.client_payload.package_version }}" as string;/g' src/compiler/corePublic.ts
-        npm install
+        npm ci
         gulp LKG
         npm test
         git diff
@@ -38,7 +38,7 @@ jobs:
         git add tests/baselines/reference/api/typescript.d.ts
         git add tests/baselines/reference/api/tsserverlibrary.d.ts
         git add ./lib
-        git config user.email "ts_bot@rcavanaugh.com"
+        git config user.email "typescriptbot@microsoft.com"
         git config user.name "TypeScript Bot"
         git commit -m 'Bump version to ${{ github.event.client_payload.package_version }} and LKG'
         git push

.github/workflows/sync-branch.yaml

@@ -25,10 +25,10 @@ jobs:
     # required client_payload members:
     # branch_name - the target branch
     - run: |
-        git config user.email "ts_bot@rcavanaugh.com"
+        git config user.email "typescriptbot@microsoft.com"
         git config user.name "TypeScript Bot"
         git fetch origin master
         git merge origin/master --no-ff
-        npm install
+        npm ci
         npm test
         git push

.github/workflows/update-lkg.yml

@@ -17,9 +17,9 @@ jobs:
 
     - name: Configure Git and Update LKG
       run: |
-        git config user.email "ts_bot@rcavanaugh.com"
+        git config user.email "typescriptbot@microsoft.com"
         git config user.name "TypeScript Bot"
-        npm install
+        npm ci
         gulp LKG
         npm test
         git diff

.github/workflows/update-package-lock.yaml

@@ -0,0 +1,28 @@
+name: Update package-lock.json
+
+on:
+    schedule:
+        # This is probably 6am UTC, which is 10pm PST or 11pm PDT
+        # Alternatively, 6am local is also fine
+        - cron: '0 6 * * *'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+    - uses: actions/setup-node@v1
+      with:
+        node-version: 12
+        registry-url: https://registry.npmjs.org/
+
+    - name: Configure git and update package-lock.json
+      run: |
+        git config user.email "[email protected]"
+        git config user.name "TypeScript Bot"
+        npm install --package-lock-only
+        git add -f package-lock.json
+        if git commit -m "Update package-lock.json"; then
+          git push
+        fi

.npmrc

@@ -18,7 +18,7 @@ branches:
 
 install:
   - npm uninstall typescript --no-save
-  - npm install
+  - npm ci
 
 cache:
   directories:

.travis.yml

@@ -47,14 +47,24 @@
       "console": "integratedTerminal",
       "outFiles": [
         "${workspaceRoot}/built/local/run.js"
-      ]
+      ],
+
+      // NOTE: To use this, you must switch the "type" above to "pwa-node". You may also need to follow the instructions
+      // here: https://github.com/microsoft/vscode-js-debug#nightly-extension to use the js-debug nightly until
+      // this feature is shipping in insiders or to a release:
+      // "customDescriptionGenerator": "'__tsDebuggerDisplay' in this ? this.__tsDebuggerDisplay(defaultValue) : defaultValue"
     },
     {
       // See: https://github.com/microsoft/TypeScript/wiki/Debugging-Language-Service-in-VS-Code
       "type": "node",
       "request": "attach",
       "name": "Attach to VS Code TS Server via Port",
-      "processId": "${command:PickProcess}"
+      "processId": "${command:PickProcess}",
+
+      // NOTE: To use this, you must switch the "type" above to "pwa-node". You may also need to follow the instructions
+      // here: https://github.com/microsoft/vscode-js-debug#nightly-extension to use the js-debug nightly until
+      // this feature is shipping in insiders or to a release:
+      // "customDescriptionGenerator": "'__tsDebuggerDisplay' in this ? this.__tsDebuggerDisplay(defaultValue) : defaultValue"
     }
   ]
 }

.vscode/launch.template.json

@@ -47,6 +47,27 @@ In general, things we find useful when reviewing suggestions are:
 
 # Instructions for Contributing Code
 
+## What You'll Need
+
+0. [A bug or feature you want to work on](https://github.com/microsoft/TypeScript/labels/help%20wanted)!
+1. [A GitHub account](https://github.com/join).
+2. A copy of the TypeScript code. See the next steps for instructions.
+3. [Node](https://nodejs.org), which runs JavaScript locally. Current or LTS will both work.
+4. An editor. [VS Code](https://code.visualstudio.com) is the best place to start for TypeScript.
+5. The gulp command line tool, for building and testing changes. See the next steps for how to install it.
+
+## Get Started
+
+1. Install node using the version you downloaded from [nodejs.org](https://nodejs.org).
+2. Open a terminal.
+3. Make a fork—your own copy—of TypeScript on your GitHub account, then make a clone—a local copy—on your computer. ([Here are some step-by-step instructions](https://github.com/anitab-org/mentorship-android/wiki/Fork%2C-Clone-%26-Remote)). Add `--depth=1` to the end of the `git clone` command to save time.
+4. Install the gulp command line tool: `npm install -g gulp-cli`
+5. Change to the TypeScript folder you made: `cd TypeScript`
+6. Install dependencies: `npm ci`
+7. Make sure everything builds and tests pass: `gulp runtests-parallel`
+8. Open the Typescript folder in your editor.
+9. Follow the directions below to add and debug a test.
+
 ## Tips
 
 ### Faster clones
@@ -65,8 +86,6 @@ TypeScript is currently accepting contributions in the form of bug fixes. A bug
 
 Features (things that add new or improved functionality to TypeScript) may be accepted, but will need to first be approved (labelled ["help wanted"](https://github.com/Microsoft/TypeScript/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) or in the "Backlog" milestone) by a TypeScript project maintainer in the suggestion issue. Features with language design impact, or that are adequately satisfied with external tools, will not be accepted.
 
-Design changes will not be accepted at this time. If you have a design change proposal, please log a suggestion issue.
-
 ## Legal
 
 You will need to complete a Contributor License Agreement (CLA). Briefly, this agreement testifies that you are granting us permission to use the submitted change according to the terms of the project's license, and that the work being submitted is under appropriate copyright. Upon submitting a pull request, you will automatically be given instructions on how to sign the CLA.
@@ -76,16 +95,11 @@ You will need to complete a Contributor License Agreement (CLA). Briefly, this a
 Your pull request should:
 
 * Include a description of what your change intends to do
-* Be a child commit of a reasonably recent commit in the **master** branch
-    * Requests need not be a single commit, but should be a linear sequence of commits (i.e. no merge commits in your PR)
-* It is desirable, but not necessary, for the tests to pass at each commit
-* Have clear commit messages
-    * e.g. "Minor refactor in goToTypeDefinition", "Fix iterated type in for-await-of", "Add test for preserveWatchOutput on command line"
+* Be based on reasonably recent commit in the **master** branch
 * Include adequate tests
     * At least one test should fail in the absence of your non-test code changes. If your PR does not match this criteria, please specify why
     * Tests should include reasonable permutations of the target fix/change
     * Include baseline changes with your change
-    * All changed code must have 100% code coverage
 * Follow the code conventions described in [Coding guidelines](https://github.com/Microsoft/TypeScript/wiki/Coding-guidelines)
 * To avoid line ending issues, set `autocrlf = input` and `whitespace = cr-at-eol` in your git configuration
 
@@ -149,37 +163,35 @@ You can also use the [provided VS Code launch configuration](./.vscode/launch.te
 
 ## Adding a Test
 
-To add a new test case, simply place a `.ts` file in `tests\cases\compiler` containing code that exemplifies the bugfix or change you are making.
+To add a new test case, add a `.ts` file in `tests\cases\compiler` with code that shows the your bug is now fixed, or your new feature now works.
 
 These files support metadata tags in the format  `// @metaDataName: value`.
 The supported names and values are the same as those supported in the compiler itself, with the addition of the `fileName` flag.
 `fileName` tags delimit sections of a file to be used as separate compilation units.
-They are useful for tests relating to modules.
+They are useful for testing modules.
 See below for examples.
 
-**Note** that if you have a test corresponding to a specific spec compliance item, you can place it in `tests\cases\conformance` in an appropriately-named subfolder.
-**Note** that filenames here must be distinct from all other compiler testcase names, so you may have to work a bit to find a unique name if it's something common.
+**Note** that if you have a test corresponding to a specific area of spec compliance, you can put it in the appropriate subfolder of `tests\cases\conformance`.
+**Note** that test filenames must be distinct from all other test names, so you may have to work a bit to find a unique name if it's something common.
 
 ### Tests for multiple files
 
-When one needs to test for scenarios which require multiple files, it is useful to use the `fileName` metadata tag as such:
+When you need to mimic having multiple files in a single test to test features such as "import", use the `filename` tag:
 
-```TypeScript
-// @fileName: file1.ts
+```ts
+// @filename: file1.ts
 export function f() {
 }
 
-// @fileName: file2.ts
+// @filename: file2.ts
 import { f as g } from "file1";
 
 var x = g();
 ```
 
-One can also write a project test, but it is slightly more involved.
-
 ## Managing the Baselines
 
-Compiler testcases generate baselines that track the emitted `.js`, the errors produced by the compiler, and the type of each expression in the file. Additionally, some testcases opt in to baselining the source map output.
+Compiler tests generate baselines: one file each for the emitted `.js`, the errors produced by the compiler, the type of each expression, and symbol for each identifier. Additionally, some tests generate baselines for the source map output.
 
 When a change in the baselines is detected, the test will fail. To inspect changes vs the expected baselines, use
 
@@ -193,7 +205,8 @@ After verifying that the changes in the baselines are correct, run
 gulp baseline-accept
 ```
 
-to establish the new baselines as the desired behavior. This will change the files in `tests\baselines\reference`, which should be included as part of your commit. It's important to carefully validate changes in the baselines.
+This will change the files in `tests\baselines\reference`, which should be included as part of your commit.
+Be sure to validate the changes carefully -- apparently unrelated changes to baselines can be clues about something you didn't think of.
 
 ## Localization
 

CONTRIBUTING.md

@@ -2,6 +2,6 @@
 FROM node:current
 COPY . /typescript
 WORKDIR /typescript
-RUN npm install
+RUN npm ci
 RUN npm i -g gulp-cli
 RUN gulp configure-insiders && gulp LKG && gulp clean && npm pack .

Dockerfile

@@ -413,7 +413,7 @@ const cleanTypesMap = () => del("built/local/typesMap.json");
 cleanTasks.push(cleanTypesMap);
 
 // Drop a copy of diagnosticMessages.generated.json into the built/local folder. This allows
-// it to be synced to the Azure DevOps repo, so that it can get picked up by the build 
+// it to be synced to the Azure DevOps repo, so that it can get picked up by the build
 // pipeline that generates the localization artifacts that are then fed into the translation process.
 const builtLocalDiagnosticMessagesGeneratedJson = "built/local/diagnosticMessages.generated.json";
 const copyBuiltLocalDiagnosticMessages = () => src(diagnosticMessagesGeneratedJson)
@@ -591,7 +591,7 @@ task("LKG").flags = {
     "   --built": "Compile using the built version of the compiler.",
 };
 
-const generateSpec = () => exec("cscript", ["//nologo", "scripts/word2md.js", path.resolve("doc/TypeScript Language Specification.docx"), path.resolve("doc/spec.md")]);
+const generateSpec = () => exec("cscript", ["//nologo", "scripts/word2md.js", path.resolve("doc/TypeScript Language Specification - ARCHIVED.docx"), path.resolve("doc/spec-ARCHIVED.md")]);
 task("generate-spec", series(buildScripts, generateSpec));
 task("generate-spec").description = "Generates a Markdown version of the Language Specification";
 

Gulpfile.js

@@ -44,7 +44,6 @@ with any additional questions or comments.
 
 *  [TypeScript in 5 minutes](https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes.html)
 *  [Programming handbook](https://www.typescriptlang.org/docs/handbook/basic-types.html)
-*  [Language specification](https://github.com/microsoft/TypeScript/blob/master/doc/spec.md)
 *  [Homepage](https://www.typescriptlang.org/)
 
 ## Building
@@ -67,7 +66,7 @@ Install [Gulp](https://gulpjs.com/) tools and dev dependencies:
 
 ```bash
 npm install -g gulp
-npm install
+npm ci
 ```
 
 Use one of the following to build and test:

README.md

@@ -3,7 +3,7 @@
 This directory contains miscellaneous documentation such as the TypeScript language specification and logo.
 If you are looking for more introductory material, you might want to take a look at the [TypeScript Handbook](https://github.com/Microsoft/TypeScript-Handbook).
 
-# Spec Contributions
-
-The specification is first authored as a Microsoft Word (docx) file and then generated into Markdown and PDF formats.
-Due to the binary format of docx files, and the merging difficulties that may come with it, it is preferred that **any suggestions or problems found in the spec should be [filed as issues](https://github.com/Microsoft/TypeScript/issues/new)** rather than sent as pull requests.
+
+# Archived Spec
+
+NOTE: the files in this directory are NOT meant to be edited. They are a snapshot of the out-of-date specification which is no longer being updated. We will not be accepting changes to these documents.