final-hill / decorator-contracts Goto Github PK

https://en.wikipedia.org/wiki/Assertion_(software_development)

Requirements

• The assertion function must be documented. #1
• The assertion function must support assertion signatures from TypeScript 3.7+. #21
• Assertions must be toggleable. #8
• Assertions must support throwing custom error types. #22
• Assertions must return a boolean in all modes. #23

Overview

Performing assertions across a code-base can be redundant and time-consuming. To mitigate this impact on efficiency, a means of disabling assertion checks must be provided. The intent being that during development and debugging the assertions would be executed, but in a production environment the checks would not be performed and instead simply return true.

This should not be a global flag, but a granular one to provide flexibility

Tasks

• Add Unit Test
• Implementation
• Update README

There is more public familiarity with GitHub than Azure, plus there is more simplicity currently. Now that Microsoft owns GitHub there is less of a desire to remain in the old location in order to leverage to benefits.

Tasks

• Migrate code
• Migrate issues
• Configure CI (#103, #104, #124)
• Configure CD (#124)
• Delete Azure DevOps repo
• Replace local repos with this one
• Change @thenewobjective namespace to @final-hill (#102)

• Add Unit Test
• Implementation
• Update README

• Add documentation to README
• Add Unit Test
• Implementation

• Disable Azure Devops branch validation
• Update build.yml
• Update validation.yml

• Add JSDoc
• Update README

References

• microsoft/TypeScript#32695
• https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions
• microsoft/TypeScript#36931

Tasks

• Implementation
• Update README

@invariant<Stack<any>>(self => ...)
class Stack<T> {
    ...
}

• Create Unit test

import Contracts from '@thenewobjective/decorator-contracts'

let checkedContracts = new Contracts(true),
    uncheckedContracts = new Contracts(false)

• The contracts constructor accepts a single boolean parameter called "checkMode". #24

• This mode dictates the runtime behavior of its associated method implementations.

• This mode is exposed as a readonly property of the instantiated object

• Add JSDoc

• Implement Unit Test

• Implementation

• Rename debugMode variable to checkMode

• Updated README

• Update JSDoc
• Update README

• The 'invariant' declaration must be documented. #27
• The invariant decorator must be class decorator only. #28
• There can be multiple invariant decorators assigned to a class. #29
• The subclasses of a contracted class must obey the invariants #30
• A truthy invariant does not throw an exception when evaluated. #31
• A falsy invariant throws an exception when evaluated. #32
• An invariant is evaluated after it's associated class is constructed. #33
• An invariant is evaluated before and after every method call on the associated class. #34
• Public properties must be forbidden. #35
• A class feature with a decorator must not be functional until the @invariant is defined. #36
• The invariant decorator has a checked mode and unchecked mode. #37
• In checked mode the invariant is evaluated #38
• In unchecked mode the invariant is not evaluated. #39
• A subclass with its own invariants must enforce all ancestor invariants. #40
• @invariant supports use with no arguments. #41
• There can be multiple invariants assigned to a contract #178

• Add explicit .npmrc file
• run npm audit on build

Azure Pipelines: "ms-azure-devops.azure-pipelines"
Azure Repos: "ms-vsts.team"
EditorConfig for VS Code: "editorconfig.editorconfig"
TSLint: "ms-vscode.vscode-typescript-tslint-plugin"
markdownlint: "davidanson.vscode-markdownlint"

• Add documentation to README
• Add Unit Test
• Implementation

• Add JSDoc
• Update README

• Add documentation to README
• Add Unit test
• Implementation

• Add Unit Test
• Implementation
• Update README

• Add documentation to README
• Add Unit Test
• Implementation

"""
The notions of “stronger” and “weaker” are formally defined from logic: P1 is said to be stronger than P2, and P2 weaker than P1, if P1 implies P2 and they are not equal. As every proposition implies True, and False implies every proposition, it is indeed legitimate to speak of True as the weakest and False as the strongest of all possible assertions.
""" -- Meyer p. 358

The class invariant must not be weaker than the invariant in the superclass. Practically this means that all invariant assertions across classes in the hierarchy are ANDed together.

• Implement functionality
• Implement Unit Tests
• Update README

References

• https://www.tutorialspoint.com/java/java_overriding.htm

Requirements

• The 'override' decorator must be documented. #43
• A subclass with an overriding member missing @OverRide is an error. #48
• Accessors must support @OverRide. #50
• Contravariance of method arguments in the subtype. #51
• In production mode the @OverRide decorator is a no-op. #45
• Only a single @OverRide can be assigned to a member per class. #54
• The 'override' decorator must not be functional until the invariant decorator is defined. #53
• The 'override' decorator must have a Contracted class in it's ancestry #170
• The override decorator is a non-static member decorator only. #44
• The parameter names and positions of an overridden method must match its ancestor's. #52
• TypeScript support? #49
• Using @OverRide on a class member with no ancestor member is an error. #46
• Using @OverRide on a method with an ancestor with a different parameter count is an error. #47

https://docs.microsoft.com/en-us/azure/devops/artifacts/get-started-npm?view=azure-devops&tabs=windows

• Update JSDoc
• Update README

• Add Unit Test
• Implementation
• Update README

• Add documentation to README
• Add Unit Test
• Implementation

To guarantee invariants remain valid, public property definitions are forbidden. All interactions with a contracted class must be done through a method or accessor.

• Create Unit Test
• Freeze class
• Update README

Linting must be enabled to enforce code conventions and provide additional semantic checks

• Remove unused dependencies

Description

Redundant checking can negatively impact efficiency. A flag should be provided to toggle the execution of assertions in a module.

Disabled in unchecked mode
Enabled in checked mode

Tasks

• Expose a flag on the module that toggles between implementations

• Add documentation to README
• Add Unit Test
• Implementation

• Add friendly names to the yaml files
• CI trigger for build should only occur on master branch
• Disable CI Trigger on Validation build
• Export Azure pipeline YAML file into project

• Update README
• Add Unit Test
• Implementation

References

• microsoft/TypeScript#2000
• microsoft/TypeScript#2000 (comment)
• microsoft/TypeScript#2000 (comment)

Design Limitation it seems currently:

• https://stackoverflow.com/questions/56377792/typescript-get-type-of-super-class
• microsoft/TypeScript#36165

• Add friendly names to the yaml files

Current appearance:

The yaml 'name' property doesn't seem to do anything in the portal:

But there is a portal feature available to accomplish this task on the detail screen:

This isn't reflected in the file it seems

• CI trigger for build should only occur on master branch
• Disable CI Trigger on Validation build
• Export Azure pipeline YAML file into project

@invariant
class Foo {
  private _value_: number = 0
  get value(){ return this._value }
  set value(x: number){ this._value_ = x }
} 

class Bar extends Foo {
  @override
  set value(x: number){
     console.log('set value')
    super.value = x
  }
}

Tasks

• Create Unit Test
• Implementation
• Update README

• Remove redundant Unit Tests
• @demands implementation
• Update @ensures implementation
• Update @OVERRIDES implementation
• Update @rescue implementation
• Update README

• Add Unit Test
• Implementation
• Update README

@invariant<Stack<any>>(self => ...)
class Stack<T> {
    ...
}

• Create Unit test

• Add documentation to README
• Add Unit Test
• Implementation

• Add Documentation to README
• Add Unit Test
• Implementation

• Add Unit Test
• Implementation
• Update README

• Add Unit Test
• Implementation
• Update README

Overview

https://docs.microsoft.com/en-us/azure/devops/pipelines/test/review-code-coverage-results?view=azure-devops

Tasks

• Generate and publish coverage report

  • https://stackoverflow.com/questions/24825860/code-coverage-for-jest
  • https://docs.microsoft.com/en-us/azure/devops/pipelines/languages/javascript?view=azure-devops#publish-code-coverage-results

• Integrate jest-junit

  • https://www.npmjs.com/package/jest-junit

• Publish test results

  • https://docs.microsoft.com/en-us/azure/devops/pipelines/languages/javascript?view=azure-devops#publish-test-results

• Update validation script for test publishing

• Add Unit Test
• Implementation
• Update README

Overview

Method decorators are registered but not active until this class decorator can associate them with the contractHandler and/or enforce their usage. This requirement simply allows an empty @invariant decorator to be used.

@invariant
class MyClass {
...
}

Tasks

• Implementation
• Implement overload so that parenthesis is not required
• Implement Unit Test
• Update README

/**
 * @license
 * Copyright (C) 2019 Michael L Haufe
 * SPDX-License-Identifier: GPL-2.0-only
 */

• Add licensing header to every typescript file
• Update linter to check for and inject the header

Reproduction steps

See build output:
https://dev.azure.com/thenewobjective/decorator-contracts/_build/results?buildId=207&view=logs&j=12f1170f-54f2-53f3-20dd-22fc7dff55f9

Symptom

Suggested fix

Fix the build.yaml file and use custom script instead of the format exported from the GUI designer

I agree with Zed Shaw's sentiment on this:

https://zedshaw.com/archive/why-i-algpl/

Linus's view on GPL2 vs GPL3:

https://www.youtube.com/watch?v=PaKIZ7gJlRU

Therefore "AGPL-1.0-only" seems most appropriate

https://spdx.org/licenses/AGPL-3.0-only.html

For business use and other uses, exceptions can be sold.
https://www.gnu.org/philosophy/selling-exceptions.en.html