conformance.textproto

# Copyright 2016 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

# Conformance requirements:
# See: https://github.com/google/closure-compiler/wiki/JS-Conformance-Framework

# Disallow throwing non-Error types.
requirement: {
  type: CUSTOM
  java_class: "com.google.javascript.jscomp.ConformanceRules$BanThrowOfNonErrorTypes"
  error_message:
    "Throwing non-Error types or Error itself is not allowed; "
    "throw shaka.util.Error instead."
  whitelist_regexp: "test/"
  whitelist_regexp: "node_modules/"
}
requirement: {
  type: BANNED_CODE_PATTERN
  value: "function template() { throw new Error(); }"
  error_message:
    "Throwing non-Error types or Error itself is not allowed; "
    "throw shaka.util.Error instead."
  whitelist_regexp: "test/"
  whitelist_regexp: "node_modules/"
}

# Ban accessing members of unknown types.
requirement: {
  type: CUSTOM
  java_class:
    "com.google.javascript.jscomp.ConformanceRules$"
    "BanUnknownTypedClassPropsReferences"
  error_message:
    "Using properties of unknown types is not allowed; add an "
    "explicit type to the variable."
  whitelist_regexp: "demo/"
}
requirement {
  type: CUSTOM
  java_class: "com.google.javascript.jscomp.ConformanceRules$BanUnknownThis"
  error_message:
    "Failed to infer type of \"this\"; "
    "please be explicit or use bind!"
  # Until we can get this rule updated for ES6 static methods
  # (https://github.com/google/closure-compiler/issues/2880):
  whitelist_regexp: "test/test/util/canned_idb.js"
  whitelist_regexp: "test/assets/assets_integration.js"
}

# Reject unresolved types.
requirement {
  type: CUSTOM
  java_class: "com.google.javascript.jscomp.ConformanceRules$BanUnresolvedType"
  error_message: "Failed to resolve type!"
}

# Reject global variables.
requirement {
  type: CUSTOM
  java_class: "com.google.javascript.jscomp.ConformanceRules$BanGlobalVars"
  error_message: "Global variables are not allowed!"
  whitelist_regexp: "demo/"
  whitelist_regexp: "test/"
  whitelist_regexp: "node_modules/"
}

# Disallow using "!" on nullable numbers in boolean assignment.
# Note: we can't use the pattern "var b = !n" because it causes too many
# false positives.
requirement: {
  type: BANNED_CODE_PATTERN
  value:
    "/** @param {boolean} b @param {?number} n */ "
    "function template(b, n) { b = !n; }"
  error_message:
    "Using \"!\" on nullable numbers in boolean assignment "
    "is not allowed; use an explicit comparison instead."
  whitelist_regexp: "node_modules/"
}

requirement: {
  type: BANNED_CODE_PATTERN
  value:
    "/** @param {*} a"
    "    @param {(number|string|boolean|null|undefined)} x */"
    "function template(a, x) { expect(a).toEqual(x); }"
  value:
    "/** @param {*} a"
    "    @param {(number|string|boolean|null|undefined)} x */"
    "function template(a, x) { expect(a).not.toEqual(x); }"
  error_message: "Use expect.toBe for primitives"
}

requirement: {
  type: BANNED_CODE_PATTERN
  value:
    "/** @param {BufferSource} a */"
    "function template(a) { new Uint8Array(a) }"
  value:
    "/** @param {BufferSource} a */"
    "function template(a) { new Int8Array(a) }"
  value:
    "/** @param {BufferSource} a */"
    "function template(a) { new Uint8ClampedArray(a) }"
  value:
    "/** @param {BufferSource} a */"
    "function template(a) { new Unt16Array(a) }"
  value:
    "/** @param {BufferSource} a */"
    "function template(a) { new Int16Array(a) }"
  value:
    "/** @param {BufferSource} a */"
    "function template(a) { new Uint32Array(a) }"
  value:
    "/** @param {BufferSource} a */"
    "function template(a) { new Int32Array(a) }"
  value:
    "/** @param {BufferSource} a */"
    "function template(a) { new Float32Array(a) }"
  value:
    "/** @param {BufferSource} a */"
    "function template(a) { new Float64Array(a) }"
  error_message: "Use shaka.util.BufferUtils.view* instead."
  whitelist_regexp: "lib/util/buffer_utils.js"
}

requirement: {
  type: BANNED_CODE_PATTERN
  value: "function template () { new Date().getTime() }"
  error_message: "Use Date.now() instead."
}

# Disallow console logging.
requirement: {
  type: BANNED_PROPERTY_CALL
  value: "Console.prototype.debug"
  value: "Console.prototype.log"
  value: "Console.prototype.info"
  value: "Console.prototype.warn"
  value: "Console.prototype.error"
  error_message:
    "Using \"console\" is not allowed; "
    "use shaka.log instead"
  whitelist_regexp: "demo/"
  whitelist_regexp: "lib/debug/log.js"
  whitelist_regexp: "test/test/boot.js"
  whitelist_regexp: "node_modules/"
  whitelist_regexp: "[synthetic:es6/promise/promise]"
}

# Disallow querySelector and querySelectorAll since they aren't supported on
# Shaka Player Embedded.
requirement: {
  type: BANNED_PROPERTY_CALL
  value: "Element.prototype.querySelector"
  value: "Document.prototype.querySelector"
  value: "Element.prototype.querySelectorAll"
  value: "Document.prototype.querySelectorAll"
  error_message: "Use getElementsByTagName"
  whitelist_regexp: "demo/"
  whitelist_regexp: "ui/"
  whitelist_regexp: "test/"
  whitelist_regexp: "node_modules/"
}

# Disallow Element.children.
requirement: {
  type: BANNED_PROPERTY
  value: "Element.prototype.children"
  error_message:
    "Using \"Element.children\" is not allowed; "
    "use Node.childNodes instead"
}

requirement: {
  type: BANNED_PROPERTY
  value: "DataView.prototype.buffer"
  value: "TypedArray.prototype.buffer"
  error_message:
    "Using \"TypedArray.buffer\" is not safe since it doesn\'t "
    "handle sub-arrays"
  whitelist_regexp: "lib/util/buffer_utils.js"
  whitelist_regexp: "lib/util/object_utils.js"
  whitelist_regexp: "test/util/buffer_utils_unit.js"
}

# Disallow Element.innerHTML and outerHTML.
requirement: {
  type: BANNED_PROPERTY
  value: "Element.prototype.innerHTML"
  value: "Element.prototype.outerHTML"
  error_message:
    "Using \"Element.innerHTML\" or \"Element.outerHTML\" is not "
    "allowed due to security concerns; use textContent, "
    "appendChild, or removeChild instead"
  whitelist_regexp: "test/test/util/util.js"
}

# Disallow DOMRect.x and y.
requirement: {
  type: BANNED_PROPERTY
  value: "DOMRect.prototype.x"
  value: "DOMRect.prototype.y"
  error_message:
    "DOMRect \"x\" and \"y\" are not supported on legacy Edge; "
    "use \"left\" and \"top\" instead."
  # The built-in set and map polyfills trigger this ban somehow.
  whitelist_regexp: "synthetic:es6/"
}

# Disallow fdescribe.
requirement: {
  type: BANNED_NAME
  value: "fdescribe"
  error_message: "Using \"fdescribe\" is not allowed"
}

# Disallow fit.
requirement: {
  type: BANNED_NAME
  value: "fit"
  error_message: "Using \"fit\" is not allowed"
  whitelist_regexp: "test/player_external.js"
}

# Disallow setInterval.
requirement: {
  type: BANNED_NAME
  value: "window.setInterval"
  error_message:
    "setInterval has several drawbacks, most of "
    "all difficulty canceling and surprising behavior "
    "when the device goes to sleep. Please use "
    "shaka.util.Timer instead."
  whitelist_regexp: "demo/"
  whitelist_regexp: "test/"
}
requirement: {
  type: BANNED_NAME
  value: "setInterval"
  error_message:
    "setInterval has several drawbacks, most of "
    "all difficulty canceling and surprising behavior "
    "when the device goes to sleep. Please use "
    "shaka.util.Timer instead."
  whitelist_regexp: "demo/"
  whitelist_regexp: "test/"
}

# Disallow setTimeout.
requirement: {
  type: BANNED_NAME
  value: "window.setTimeout"
  error_message:
    "setTimeout has several drawbacks, most of "
    "all difficulty canceling it. Please use "
    "shaka.util.Timer instead."
  whitelist_regexp: "demo/"
  whitelist_regexp: "test/"
  whitelist_regexp: "lib/util/delayed_tick.js"
}
requirement: {
  type: BANNED_NAME
  value: "setTimeout"
  error_message:
    "setTimeout has several drawbacks, most of "
    "all difficulty canceling it. Please use "
    "shaka.util.Timer instead."
  whitelist_regexp: "demo/"
  whitelist_regexp: "test/"
}

# Disallow eval, except when testing for modern JS syntax in demo
requirement: {
  type: BANNED_NAME
  value: "window.eval"
  error_message: "Using \"eval\" is not allowed"
  whitelist_regexp: "demo/demo_utils.js"
  whitelist_regexp: "node_modules/google-closure-library/closure/goog/base.js"
  whitelist_regexp: "test/util/functional_unit.js"
}
requirement: {
  type: BANNED_NAME
  value: "eval"
  error_message: "Using \"eval\" is not allowed"
  whitelist_regexp: "demo/demo_utils.js"
  whitelist_regexp: "node_modules/google-closure-library/closure/goog/base.js"
  whitelist_regexp: "test/util/functional_unit.js"
}

# Disallow ES6 methods.
requirement: {
  type: BANNED_PROPERTY
  value: "ArrayBuffer.prototype.slice"
  error_message:
    "ArrayBuffer.slice is not allowed because it "
    "is not supported on Tizen 2016"
}

# Disallow the general use of fetch, which is not available on all supported
# platforms.
requirement: {
  type: BANNED_NAME_CALL
  value: "fetch"
  value: "window.fetch"
  error_message:
    "Using \"fetch\" directly is not allowed; "
    "use shaka.test.Util.fetch or NetworkingEngine.request "
    "instead."
  whitelist_regexp: "lib/net/http_fetch_plugin.js"
}

# Disallow the use of generators, which are a major performance issue.  See
# https://github.com/shaka-project/shaka-player/issues/4062#issuecomment-1079428268
requirement: {
  type: BANNED_CODE_PATTERN
  value:
    "/** @param {*} x */ "
    "function *template(x) { yield x; }"
  error_message:
    "ES6 generators are a major performance issue!  Find another solution. "
    "See also https://bit.ly/3wAsoj5"
  whitelist_regexp: "node_modules/"
}