cognitive-complexity-ts 0.6.4 → 0.7.0

package/build/src/cognitive-complexity/Scope.d.ts

@@ -13,6 +13,10 @@ export declare class Scope {
     readonly object: ReadonlyArray<string>;
     constructor(local: ReadonlyArray<string>, object: ReadonlyArray<string>);
     includes(name: string): boolean;
+    /**
+     * @returns a new scope with the identifier from the node included,
+     *          or if there is no identifier, it returns the scope not modified nor cloned
+     */
     maybeAdd(node: ts.Node, variableBeingDefined: string | undefined): Scope;
     private scopeToAdd;
 }

package/build/src/cognitive-complexity/Scope.js

@@ -17,6 +17,10 @@ class Scope {
     includes(name) {
         return this.local.includes(name) || this.object.includes(name);
     }
+    /**
+     * @returns a new scope with the identifier from the node included,
+     *          or if there is no identifier, it returns the scope not modified nor cloned
+     */
     maybeAdd(node, variableBeingDefined) {
         const { local, object } = this.scopeToAdd(node, variableBeingDefined);
         if (local.length !== 0 || object.length !== 0) {

package/build/src/cognitive-complexity/cognitive-complexity.js

@@ -15,36 +15,54 @@ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (
 }) : function(o, v) {
     o["default"] = v;
 });
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
-};
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.fileCost = void 0;
+exports.fileCost = fileCost;
 const ts = __importStar(require("typescript"));
-const util_1 = require("../util/util");
 const node_naming_1 = require("./node-naming");
 const depth_1 = require("./depth");
 const node_inspection_1 = require("./node-inspection");
 const Scope_1 = require("./Scope");
 function fileCost(file) {
-    return nodeCost(file, true);
+    const initialContext = {
+        depth: 0,
+        scope: new Scope_1.Scope([], []),
+        topLevel: true,
+        variableBeingDefined: undefined,
+    };
+    const initialMutableContext = {
+        precedingOperator: undefined,
+        precedingTypeOperator: undefined,
+    };
+    return nodeCost(file, initialContext, initialMutableContext);
 }
-exports.fileCost = fileCost;
-function aggregateCostOfChildren(children, childDepth, topLevel, scope, variableBeingDefined) {
+function aggregateCostOfChildren(children, ctx, mutCtx) {
     let score = 0;
     // The inner containers of a node is defined as the concat of:
     // * all child nodes that are functions/namespaces/classes
     // * all containers declared directly under a non-container child node
     const inner = [];
     for (const child of children) {
-        const childCost = nodeCost(child, topLevel, childDepth, scope, variableBeingDefined);
+        const childCost = nodeCost(child, ctx, mutCtx);
         score += childCost.score;
         // a function/class/namespace/type is part of the inner scope we want to output
-        const name = (0, node_naming_1.chooseContainerName)(child, variableBeingDefined);
+        const name = (0, node_naming_1.chooseContainerName)(child, ctx.variableBeingDefined);
         if (name !== undefined) {
             inner.push({
                 ...(0, node_inspection_1.getColumnAndLine)(child),
@@ -57,10 +75,7 @@ function aggregateCostOfChildren(children, childDepth, topLevel, scope, variable
             inner.push(...childCost.inner);
         }
     }
-    return {
-        score,
-        inner
-    };
+    return { score, inner };
 }
 function costOfDepth(node, depth) {
     // increment for nesting level
@@ -89,9 +104,9 @@ function costOfDepth(node, depth) {
     }
     return 0;
 }
-function inherentCost(node, scope) {
+function inherentCost(node, scope, mutCtx) {
     // certain language features carry and inherent cost
-    if ((0, node_inspection_1.isSequenceOfDifferentBooleanOperations)(node)
+    if ((0, node_inspection_1.isNewSequenceOfBinaryOperators)(node, mutCtx.precedingOperator)
         || ts.isCatchClause(node)
         || ts.isConditionalExpression(node)
         || ts.isConditionalTypeNode(node)
@@ -102,7 +117,8 @@ function inherentCost(node, scope) {
         || ts.isMappedTypeNode(node)
         || ts.isSwitchStatement(node)
         || ts.isWhileStatement(node)
-        || (0, node_inspection_1.isBreakOrContinueToLabel)(node)) {
+        || (0, node_inspection_1.isBreakOrContinueToLabel)(node)
+        || (0, node_inspection_1.isNewSequenceOfBinaryTypeOperators)(node, mutCtx.precedingTypeOperator)) {
         return 1;
     }
     const calledName = (0, node_naming_1.getNameIfCalledNode)(node);
@@ -126,61 +142,91 @@ function inherentCost(node, scope) {
         }
         return score;
     }
-    if ((0, node_inspection_1.isBinaryTypeOperator)(node)) {
-        // This node naturally represents a sequence of binary type operators.
-        // (unlike normal binary operators)
-        let score = 1;
-        // However, this sequence can contain nodes that are a different binary operator.
-        // We can assume that children of the internal syntax list that are binary operators
-        // are not the same kind as this node.
-        // Binary sub-expressions at either end of the syntax list
-        // do not break this sequence of operators in the code; they merely bookend it.
-        const syntaxList = node.getChildren()[0];
-        const numOfSequenceInterrupts = (0, util_1.countNotAtTheEnds)(syntaxList.getChildren(), node_inspection_1.isBinaryTypeOperator);
-        score += numOfSequenceInterrupts;
-        return score;
-    }
     return 0;
 }
 /**
  * @param node The node whose cost we want
- * @param topLevel Whether the node is at the top level of a file
- * @param depth The depth the node is at
- * @param scope The scope at the node
+ * @param ctx Information about the context a node is in, which is needed to know the node cost.
+ * @param mutCtx Same as above, but this information can be changed while traversing,
+ *               which will provide information up the call stack (where this function is called and higher).
  */
-function nodeCost(node, topLevel, depth = 0, scope = new Scope_1.Scope([], []), variableBeingDefined = undefined) {
-    let score = inherentCost(node, scope);
-    score += costOfDepth(node, depth);
+function nodeCost(node, ctx, mutCtx) {
+    const { depth, topLevel, scope, variableBeingDefined } = ctx;
     // get the ancestors container names from the perspective of this node's children
-    const namedAncestorsOfChildren = scope
-        .maybeAdd(node, variableBeingDefined);
-    const { same, below } = (0, depth_1.whereAreChildren)(node);
+    const scopeForChildren = scope.maybeAdd(node, variableBeingDefined);
+    const { sameDepth, below } = (0, depth_1.whereAreChildren)(node);
     /**
      * The name being introduced (if there is one)
      * for a variable whose declaration this scope is directly inside of.
      * It is used to give names to anonymous functions and classes.
-     * let a =    $a$         () => {};
-     * let a =  ( $a$         () => {} );
-     * let a = f( $undefined$ () => {} );
-     * let a =                      () => { $undefined$ };
+     * let a =    $a$         () => { $anonymous$ };
+     * let a =  ( $a$         () => { $anonymous$ } );
+     * let a = f( $anonymous$ () => { $anonymous$ } );
      */
     let newVariableBeingDefined = (0, node_naming_1.getNameOfAssignment)(node);
     if (newVariableBeingDefined === undefined
+        && variableBeingDefined !== undefined
         && (0, node_inspection_1.passThroughNameBeingAssigned)(node)) {
         newVariableBeingDefined = variableBeingDefined;
     }
-    const costOfSameDepthChildren = aggregateCostOfChildren(same, depth, topLevel, namedAncestorsOfChildren, newVariableBeingDefined);
-    // The nodes below this node have the same depth number,
-    // iff this node is top level and it is a container.
-    const container = (0, node_inspection_1.isContainer)(node);
-    const depthOfBelow = depth + (topLevel && container ? 0 : 1);
-    const costOfBelowChildren = aggregateCostOfChildren(below, depthOfBelow, false, namedAncestorsOfChildren, newVariableBeingDefined);
+    const opSequenceInProgress = mutCtx.precedingOperator;
+    const typeOpSequenceInProgress = mutCtx.precedingTypeOperator;
+    const pauseOpSequence = (0, node_inspection_1.pausesASequenceOfBinaryOperators)(node);
+    const pauseTypeOpSequence = (0, node_inspection_1.pausesASequenceOfBinaryTypeOperators)(node);
+    // Check if the node ends any ongoing sequence of binary operators
+    if ((0, node_inspection_1.breaksASequenceOfBinaryOperators)(node)) {
+        mutCtx.precedingTypeOperator = undefined;
+        mutCtx.precedingOperator = undefined;
+    }
+    // Score for the current node
+    let score = inherentCost(node, scope, mutCtx);
+    score += costOfDepth(node, depth);
+    // If this is a binary operator, there won't be any children.
+    // Pass along the operator info
+    if ((0, node_inspection_1.isChainableBinaryOperator)(node)) {
+        mutCtx.precedingOperator = node.kind;
+    }
+    // If this is a binary type operator, there won't be any children.
+    // Pass along the operator info
+    else if ((0, node_inspection_1.isChainableBinaryTypeOperator)(node)) {
+        mutCtx.precedingTypeOperator = node.kind;
+    }
+    else if (pauseOpSequence) {
+        mutCtx.precedingOperator = undefined;
+    }
+    else if (pauseTypeOpSequence) {
+        mutCtx.precedingTypeOperator = undefined;
+    }
+    const ctxForChildrenSameDepth = {
+        depth,
+        topLevel,
+        precedingOperator: mutCtx.precedingOperator,
+        scope: scopeForChildren,
+        variableBeingDefined: newVariableBeingDefined,
+    };
+    const costOfSameDepthChildren = aggregateCostOfChildren(sameDepth, ctxForChildrenSameDepth, mutCtx);
+    // The nodes below this node have an increased depth number,
+    // unless this node is top level and it is a container.
+    const depthOfBelow = depth + (topLevel && (0, node_inspection_1.isContainer)(node) ? 0 : 1);
+    const ctxForChildrenBelow = {
+        ...ctxForChildrenSameDepth,
+        depth: depthOfBelow,
+        topLevel: false,
+    };
+    const costOfBelowChildren = aggregateCostOfChildren(below, ctxForChildrenBelow, mutCtx);
+    // continue a paused sequence
+    if (pauseOpSequence) {
+        mutCtx.precedingOperator = opSequenceInProgress;
+    }
+    else if (pauseTypeOpSequence) {
+        mutCtx.precedingTypeOperator = typeOpSequenceInProgress;
+    }
     score += costOfSameDepthChildren.score;
     score += costOfBelowChildren.score;
-    const inner = [...costOfSameDepthChildren.inner, ...costOfBelowChildren.inner];
-    return {
-        inner,
-        score,
-    };
+    const inner = [
+        ...costOfSameDepthChildren.inner,
+        ...costOfBelowChildren.inner
+    ];
+    return { inner, score };
 }
 //# sourceMappingURL=cognitive-complexity.js.map

package/build/src/cognitive-complexity/debug.d.ts

@@ -1,3 +1,3 @@
 import * as ts from "typescript";
-export declare const testLog: (msg: string, ...param: any[]) => void;
+export declare const testLog: import("util").DebugLogger;
 export declare function logNode(child: ts.Node): void;

package/build/src/cognitive-complexity/debug.js

@@ -1,10 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.logNode = exports.testLog = void 0;
+exports.testLog = void 0;
+exports.logNode = logNode;
 const util_1 = require("util");
 exports.testLog = (0, util_1.debuglog)("test");
 function logNode(child) {
     (0, exports.testLog)(child.getFullText());
 }
-exports.logNode = logNode;
 //# sourceMappingURL=debug.js.map

package/build/src/cognitive-complexity/depth.d.ts

@@ -6,11 +6,11 @@ interface DepthOfChildren {
     /**
      * The same level of depth.
      */
-    same: ts.Node[];
+    sameDepth: readonly ts.Node[];
     /**
      * One level of depth below.
      */
-    below: ts.Node[];
+    below: readonly ts.Node[];
 }
 /**
  * @param node The node whose children to categorise by depth

package/build/src/cognitive-complexity/depth.js

@@ -18,15 +18,25 @@ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (
 }) : function(o, v) {
     o["default"] = v;
 });
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
-};
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.whereAreChildren = void 0;
+exports.whereAreChildren = whereAreChildren;
 const ts = __importStar(require("typescript"));
 const node_util_1 = require("../util/node-util");
 const node_inspection_1 = require("./node-inspection");
@@ -39,6 +49,9 @@ function whereAreChildren(node) {
     if (ts.isArrowFunction(node)) {
         return arrowFunction(node);
     }
+    else if (ts.isBinaryExpression(node)) {
+        return binaryExpression(node);
+    }
     else if (ts.isCatchClause(node)) {
         return catchClause(node);
     }
@@ -74,20 +87,32 @@ function whereAreChildren(node) {
     }
     else {
         return {
-            same: node.getChildren(),
-            below: []
+            sameDepth: node.getChildren(),
+            below: [],
         };
     }
 }
-exports.whereAreChildren = whereAreChildren;
 function arrowFunction(node) {
     const children = node.getChildren();
     // aggregate code inside SyntaxList
-    const same = children.slice(1, -1);
+    const sameDepth = children.slice(1, -1);
     // aggregate code inside arrow function
     const below = [children[children.length - 1]];
-    return { same, below };
+    return { sameDepth, below };
 }
+function binaryExpression(node) {
+    return {
+        sameDepth: node.getChildren(),
+        below: [],
+    };
+}
+// function binaryTypeExpression(node: ts.UnionTypeNode | ts.IntersectionTypeNode): DepthOfChildren {
+//     return {
+//         sameDepth: [node.types[0]],
+//         right: node.types.slice(1),
+//         below: [],
+//     }
+// }
 function catchClause(node) {
     const children = node.getChildren();
     const variableDeclaration = children.find(child => ts.isVariableDeclaration(child));
@@ -95,7 +120,7 @@ function catchClause(node) {
     if (block === undefined)
         throw new node_util_1.UnreachableNodeState(node, "catch clause has no block");
     return {
-        same: variableDeclaration ? [variableDeclaration] : [],
+        sameDepth: variableDeclaration ? [variableDeclaration] : [],
         below: [block],
     };
 }
@@ -105,7 +130,7 @@ function conditionalExpression(node) {
     const thenCode = children[2];
     const elseCode = children[4];
     return {
-        same: [condition],
+        sameDepth: [condition],
         below: [thenCode, elseCode]
     };
 }
@@ -121,22 +146,22 @@ function conditionalType(node) {
     // else code
     below.push(...children.slice(endOfThen + 1));
     return {
-        same: condition,
+        sameDepth: condition,
         below,
     };
 }
 function doStatement(node) {
-    const same = [];
+    const sameDepth = [];
     const below = [];
     const children = node.getChildren();
     // aggregate block
     below.push(children[1]);
     // aggregate condition
-    same.push(children[4]);
-    return { same, below };
+    sameDepth.push(children[4]);
+    return { sameDepth, below };
 }
 function forLikeStatement(node) {
-    const same = [];
+    const sameDepth = [];
     const below = [];
     const children = node.getChildren();
     // consume everything form the open parenthesis to the close parenthesis
@@ -146,27 +171,24 @@ function forLikeStatement(node) {
         if (ts.isToken(child) && child.kind === ts.SyntaxKind.CloseParenToken) {
             break;
         }
-        same.push(child);
+        sameDepth.push(child);
     }
     // consume looped code
     below.push(children[i]);
-    return { same, below };
+    return { sameDepth, below };
 }
 function functionDeclaration(node) {
     const children = node.getChildren();
-    const same = children.slice(1, -1);
+    const sameDepth = children.slice(1, -1);
     const below = [children[children.length - 1]];
-    return {
-        below,
-        same,
-    };
+    return { sameDepth, below };
 }
 function functionExpression(node) {
     const children = node.getChildren();
     const functionBody = children.slice(-1);
     const functionDecl = children.slice(0, -1);
     return {
-        same: functionBody,
+        sameDepth: functionBody,
         below: functionDecl
     };
 }
@@ -179,34 +201,34 @@ function ifStatement(node) {
         if (ts.isIfStatement(elseCode)) {
             // an else if structure is on the same depth
             return {
-                same: [condition, elseCode],
+                sameDepth: [condition, elseCode],
                 below: [thenCode]
             };
         }
         else {
             // the contents of a solo else are at one depth below
             return {
-                same: [condition],
+                sameDepth: [condition],
                 below: [thenCode, elseCode]
             };
         }
     }
     return {
-        same: [condition],
+        sameDepth: [condition],
         below: [thenCode]
     };
 }
 function methodDeclaration(node) {
-    const same = [];
+    const sameDepth = [];
     const below = [];
     for (const child of node.getChildren()) {
         if (ts.isBlock(child)) {
             below.push(child);
             break;
         }
-        same.push(child);
+        sameDepth.push(child);
     }
-    return { same, below };
+    return { sameDepth, below };
 }
 function switchStatement(node) {
     const children = node.getChildren();
@@ -215,7 +237,7 @@ function switchStatement(node) {
     // consume cases
     const cases = [children[4]];
     return {
-        same: condition,
+        sameDepth: condition,
         below: cases
     };
 }
@@ -224,7 +246,7 @@ function whileStatement(node) {
     const condition = children[2];
     const loopCode = children[4];
     return {
-        same: [condition],
+        sameDepth: [condition],
         below: [loopCode]
     };
 }

package/build/src/cognitive-complexity/node-inspection.d.ts

@@ -6,12 +6,37 @@ export declare function getColumnAndLine(node: ts.Node): ColumnAndLine;
 export declare function getIdentifier(node: ts.Node): string | undefined;
 export declare function getFirstNonParenthesizedAncestor(node: ts.Node): ts.Node;
 export declare function getTextWithoutBrackets(node: ts.Node): string;
-export declare function isBinaryTypeOperator(node: ts.Node): node is ts.UnionOrIntersectionTypeNode;
 export declare function isBreakOrContinueToLabel(node: ts.Node): boolean;
 export declare function isContainer(node: ts.Node): boolean;
 export declare function isForLikeStatement(node: ts.Node): node is ForLikeStatement;
 export declare function isFunctionNode(node: ts.Node): node is FunctionNode;
-export declare function isSequenceOfDifferentBooleanOperations(node: ts.Node): boolean;
 export declare function isSyntaxList(node: ts.Node): node is ts.SyntaxList;
+export declare function isNewSequenceOfBinaryOperators(node: ts.Node, precedingOperator: ChainableBinaryOperator["kind"] | undefined): boolean;
+export declare function isNewSequenceOfBinaryTypeOperators(node: ts.Node, precedingTypeOperator: ChainableBinaryTypeOperator["kind"] | undefined): boolean;
+export type ChainableBinaryOperator = ts.Node & {
+    kind: ts.SyntaxKind.AmpersandAmpersandToken | ts.SyntaxKind.BarBarToken | ts.SyntaxKind.QuestionQuestionToken;
+};
+export declare function isChainableBinaryOperator(node: ts.Node): node is ChainableBinaryOperator;
+export type ChainableBinaryTypeOperator = ts.Node & {
+    kind: ts.SyntaxKind.AmpersandToken | ts.SyntaxKind.BarToken;
+};
+export declare function isChainableBinaryTypeOperator(node: ts.Node): node is ChainableBinaryTypeOperator;
+/**
+ * A node that causes an end to a sequence of binary operators
+ * (i.e. A && B { C && D }, the curly braces end the prior sequence;
+ * C will not be interpreted as part of the last sequence.
+ */
+export declare function breaksASequenceOfBinaryOperators(node: ts.Node): boolean;
+/**
+ * A node that doesn't cause an end to a sequence of binary operators
+ * (i.e. A && Node && B, the 2 && are in the same sequence)
+ * but the node's children don't form part of that sequence
+ * (i.e. A && Node(B && C) && D, this is two sequences, one inside Node(), the other outside)
+ */
+export declare function pausesASequenceOfBinaryOperators(node: ts.Node): node is ts.ElementAccessExpression | ts.CallLikeExpression | ts.PrefixUnaryExpression;
+/**
+ * @see {pausesASequenceOfBinaryOperators} but for type operators
+ */
+export declare function pausesASequenceOfBinaryTypeOperators(node: ts.Node): node is ts.ParenthesizedExpression | ts.TypeReferenceNode | ts.AsExpression;
 export declare function passThroughNameBeingAssigned(node: ts.Node): boolean;
 export declare function report(node: ts.Node, depth?: number): void;

package/build/src/cognitive-complexity/node-inspection.js

@@ -15,15 +15,42 @@ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (
 }) : function(o, v) {
     o["default"] = v;
 });
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
-};
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.report = exports.passThroughNameBeingAssigned = exports.isSyntaxList = exports.isSequenceOfDifferentBooleanOperations = exports.isFunctionNode = exports.isForLikeStatement = exports.isContainer = exports.isBreakOrContinueToLabel = exports.isBinaryTypeOperator = exports.getTextWithoutBrackets = exports.getFirstNonParenthesizedAncestor = exports.getIdentifier = exports.getColumnAndLine = void 0;
+exports.getColumnAndLine = getColumnAndLine;
+exports.getIdentifier = getIdentifier;
+exports.getFirstNonParenthesizedAncestor = getFirstNonParenthesizedAncestor;
+exports.getTextWithoutBrackets = getTextWithoutBrackets;
+exports.isBreakOrContinueToLabel = isBreakOrContinueToLabel;
+exports.isContainer = isContainer;
+exports.isForLikeStatement = isForLikeStatement;
+exports.isFunctionNode = isFunctionNode;
+exports.isSyntaxList = isSyntaxList;
+exports.isNewSequenceOfBinaryOperators = isNewSequenceOfBinaryOperators;
+exports.isNewSequenceOfBinaryTypeOperators = isNewSequenceOfBinaryTypeOperators;
+exports.isChainableBinaryOperator = isChainableBinaryOperator;
+exports.isChainableBinaryTypeOperator = isChainableBinaryTypeOperator;
+exports.breaksASequenceOfBinaryOperators = breaksASequenceOfBinaryOperators;
+exports.pausesASequenceOfBinaryOperators = pausesASequenceOfBinaryOperators;
+exports.pausesASequenceOfBinaryTypeOperators = pausesASequenceOfBinaryTypeOperators;
+exports.passThroughNameBeingAssigned = passThroughNameBeingAssigned;
+exports.report = report;
 const ts = __importStar(require("typescript"));
 const util_1 = require("../util/util");
 function getColumnAndLine(node) {
@@ -34,7 +61,6 @@ function getColumnAndLine(node) {
         line: lineAndCol.line + 1,
     };
 }
-exports.getColumnAndLine = getColumnAndLine;
 function getIdentifier(node) {
     for (const child of node.getChildren()) {
         if (ts.isMemberName(child) || ts.isComputedPropertyName(child)) {
@@ -43,7 +69,6 @@ function getIdentifier(node) {
     }
     return undefined;
 }
-exports.getIdentifier = getIdentifier;
 function getFirstNonParenthesizedAncestor(node) {
     let firstNonParenthesisAncestor = node.parent;
     while (ts.isParenthesizedExpression(firstNonParenthesisAncestor)) {
@@ -51,7 +76,6 @@ function getFirstNonParenthesizedAncestor(node) {
     }
     return firstNonParenthesisAncestor;
 }
-exports.getFirstNonParenthesizedAncestor = getFirstNonParenthesizedAncestor;
 function getTextWithoutBrackets(node) {
     if (ts.isParenthesizedExpression(node)) {
         return node.getChildren()
@@ -61,11 +85,6 @@ function getTextWithoutBrackets(node) {
     }
     return node.getText();
 }
-exports.getTextWithoutBrackets = getTextWithoutBrackets;
-function isBinaryTypeOperator(node) {
-    return ts.isUnionTypeNode(node) || ts.isIntersectionTypeNode(node);
-}
-exports.isBinaryTypeOperator = isBinaryTypeOperator;
 function isBreakOrContinueToLabel(node) {
     if (ts.isBreakOrContinueStatement(node)) {
         for (const child of node.getChildren()) {
@@ -76,7 +95,6 @@ function isBreakOrContinueToLabel(node) {
     }
     return false;
 }
-exports.isBreakOrContinueToLabel = isBreakOrContinueToLabel;
 function isContainer(node) {
     return isFunctionNode(node)
         || ts.isClassDeclaration(node)
@@ -87,13 +105,11 @@ function isContainer(node) {
         || ts.isSourceFile(node)
         || ts.isSourceFile(node.parent);
 }
-exports.isContainer = isContainer;
 function isForLikeStatement(node) {
     return ts.isForInStatement(node)
         || ts.isForOfStatement(node)
         || ts.isForStatement(node);
 }
-exports.isForLikeStatement = isForLikeStatement;
 function isFunctionNode(node) {
     return ts.isArrowFunction(node)
         || ts.isFunctionDeclaration(node)
@@ -101,39 +117,75 @@ function isFunctionNode(node) {
         || ts.isMethodDeclaration(node)
         || ts.isAccessor(node);
 }
-exports.isFunctionNode = isFunctionNode;
-function isSequenceOfDifferentBooleanOperations(node) {
-    var _a;
-    if (!ts.isBinaryExpression(node)) {
+function isSyntaxList(node) {
+    return node.kind === ts.SyntaxKind.SyntaxList;
+}
+function isNewSequenceOfBinaryOperators(node, precedingOperator) {
+    if (!isChainableBinaryOperator(node)
+        && node.kind !== ts.SyntaxKind.AmpersandAmpersandEqualsToken
+        && node.kind !== ts.SyntaxKind.BarBarEqualsToken
+        && node.kind !== ts.SyntaxKind.QuestionQuestionEqualsToken) {
         return false;
     }
-    const operatorToken = node.getChildAt(1);
-    if (!ts.isToken(operatorToken)) {
+    // is now an operator, or is different to previous operator
+    return precedingOperator === undefined || node.kind !== precedingOperator;
+}
+function isNewSequenceOfBinaryTypeOperators(node, precedingTypeOperator) {
+    if (!isChainableBinaryTypeOperator(node)) {
         return false;
     }
-    const operatorIsBoolean = operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandToken
-        || operatorToken.kind === ts.SyntaxKind.BarBarToken
-        || operatorToken.kind === ts.SyntaxKind.QuestionQuestionToken;
-    const firstNonParenthesisAncestor = getFirstNonParenthesizedAncestor(node);
-    if (operatorIsBoolean) {
-        // True if the parent does not use the same operator as this node.
-        // Presumably true if the parent is not a binary expression.
-        // Child number 1 is the operator token.
-        return ((_a = firstNonParenthesisAncestor.getChildAt(1)) === null || _a === void 0 ? void 0 : _a.kind) != operatorToken.kind;
-    }
-    return false;
+    return precedingTypeOperator !== node.kind;
 }
-exports.isSequenceOfDifferentBooleanOperations = isSequenceOfDifferentBooleanOperations;
-function isSyntaxList(node) {
-    return node.kind === ts.SyntaxKind.SyntaxList;
+function isChainableBinaryOperator(node) {
+    return node.kind === ts.SyntaxKind.AmpersandAmpersandToken
+        || node.kind === ts.SyntaxKind.BarBarToken
+        || node.kind === ts.SyntaxKind.QuestionQuestionToken;
+}
+function isChainableBinaryTypeOperator(node) {
+    const isPartOfTypeExpression = (node === null || node === void 0 ? void 0 : node.parent) !== undefined // this is actually undefined-able
+        && (ts.isUnionTypeNode(node.parent) || ts.isIntersectionTypeNode(node.parent)); // doing .parent skips the syntax list for some reason
+    return isPartOfTypeExpression
+        && (node.kind === ts.SyntaxKind.AmpersandToken || node.kind === ts.SyntaxKind.BarToken);
+}
+/**
+ * A node that causes an end to a sequence of binary operators
+ * (i.e. A && B { C && D }, the curly braces end the prior sequence;
+ * C will not be interpreted as part of the last sequence.
+ */
+function breaksASequenceOfBinaryOperators(node) {
+    return ts.isStatement(node)
+        || ts.isBlock(node)
+        || isFunctionNode(node)
+        || ts.isParameter(node)
+        || ts.isTypeParameterDeclaration(node)
+        || ts.isPropertyDeclaration(node)
+        || (node.kind === ts.SyntaxKind.ColonToken && isFunctionNode(node.parent))
+        || node.kind === ts.SyntaxKind.FirstAssignment; // separates extends expression from parameter default
+}
+/**
+ * A node that doesn't cause an end to a sequence of binary operators
+ * (i.e. A && Node && B, the 2 && are in the same sequence)
+ * but the node's children don't form part of that sequence
+ * (i.e. A && Node(B && C) && D, this is two sequences, one inside Node(), the other outside)
+ */
+function pausesASequenceOfBinaryOperators(node) {
+    return ts.isCallLikeExpression(node)
+        || ts.isPrefixUnaryExpression(node)
+        || ts.isElementAccessExpression(node);
+}
+/**
+ * @see {pausesASequenceOfBinaryOperators} but for type operators
+ */
+function pausesASequenceOfBinaryTypeOperators(node) {
+    return ts.isParenthesizedExpression(node)
+        || ts.isTypeReferenceNode(node)
+        || ts.isAsExpression(node);
 }
-exports.isSyntaxList = isSyntaxList;
 function passThroughNameBeingAssigned(node) {
     return isSyntaxList(node)
         || ts.isObjectLiteralExpression(node)
         || ts.isParenthesizedExpression(node);
 }
-exports.passThroughNameBeingAssigned = passThroughNameBeingAssigned;
 function report(node, depth = 0) {
     const toLog = [(0, util_1.repeat)("\t", depth), ts.SyntaxKind[node.kind], node.kind];
     console.error(...toLog);
@@ -141,5 +193,4 @@ function report(node, depth = 0) {
         report(child, depth + 1);
     }
 }
-exports.report = report;
 //# sourceMappingURL=node-inspection.js.map

package/build/src/cognitive-complexity/node-naming.js

@@ -15,15 +15,29 @@ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (
 }) : function(o, v) {
     o["default"] = v;
 });
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
-};
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getExpressionToAccessObjectMember = exports.getNameOfAssignment = exports.getNameIfCalledNode = exports.getIntroducedLocalName = exports.chooseContainerName = void 0;
+exports.chooseContainerName = chooseContainerName;
+exports.getIntroducedLocalName = getIntroducedLocalName;
+exports.getNameIfCalledNode = getNameIfCalledNode;
+exports.getNameOfAssignment = getNameOfAssignment;
+exports.getExpressionToAccessObjectMember = getExpressionToAccessObjectMember;
 const ts = __importStar(require("typescript"));
 const node_util_1 = require("../util/node-util");
 const node_inspection_1 = require("./node-inspection");
@@ -52,7 +66,6 @@ function chooseContainerName(node, variableBeingDefined) {
     }
     return undefined;
 }
-exports.chooseContainerName = chooseContainerName;
 function getIntroducedLocalName(node) {
     if (ts.isVariableDeclaration(node)) {
         return (0, node_inspection_1.getIdentifier)(node);
@@ -77,7 +90,6 @@ function getIntroducedLocalName(node) {
     }
     return undefined;
 }
-exports.getIntroducedLocalName = getIntroducedLocalName;
 function getNameIfCalledNode(node) {
     if (ts.isCallExpression(node)) {
         return getCalledFunctionName(node);
@@ -99,7 +111,6 @@ function getNameIfCalledNode(node) {
     }
     return undefined;
 }
-exports.getNameIfCalledNode = getNameIfCalledNode;
 function getNameOfAssignment(node) {
     if (ts.isVariableDeclaration(node)
         || ts.isPropertyDeclaration(node)
@@ -116,7 +127,6 @@ function getNameOfAssignment(node) {
     }
     return undefined;
 }
-exports.getNameOfAssignment = getNameOfAssignment;
 function getExpressionToAccessObjectMember(node) {
     if (ts.isMethodDeclaration(node)) {
         const [name, requiresDot] = getMethodDeclarationName(node);
@@ -138,7 +148,6 @@ function getExpressionToAccessObjectMember(node) {
     }
     return undefined;
 }
-exports.getExpressionToAccessObjectMember = getExpressionToAccessObjectMember;
 /**
  * @return [name, requires dot syntax]
  */

package/build/src/cognitive-complexity/output.js

@@ -18,15 +18,29 @@ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (
 }) : function(o, v) {
     o["default"] = v;
 });
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
-};
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.programOutput = exports.getFolderOutput = exports.getSourceOutput = exports.getFileOutput = exports.getFileOrFolderOutput = void 0;
+exports.getFileOrFolderOutput = getFileOrFolderOutput;
+exports.getFileOutput = getFileOutput;
+exports.getSourceOutput = getSourceOutput;
+exports.getFolderOutput = getFolderOutput;
+exports.programOutput = programOutput;
 const fs_1 = require("fs");
 const path = __importStar(require("path"));
 const ts = __importStar(require("typescript"));
@@ -45,19 +59,16 @@ async function getFileOrFolderOutput(entryPath) {
         return getFileOutput(entryPath);
     }
 }
-exports.getFileOrFolderOutput = getFileOrFolderOutput;
 // API
 async function getFileOutput(filePath) {
     const fileContent = (await fs_1.promises.readFile(filePath)).toString();
     return getSourceOutput(fileContent, path.basename(filePath));
 }
-exports.getFileOutput = getFileOutput;
 // API
 function getSourceOutput(sourceCode, fileName = "") {
     const parsedFile = ts.createSourceFile(fileName, sourceCode, ts.ScriptTarget.Latest, true);
     return (0, cognitive_complexity_1.fileCost)(parsedFile);
 }
-exports.getSourceOutput = getSourceOutput;
 // API
 async function getFolderOutput(folderPath) {
     const folderContents = await fs_1.promises.readdir(folderPath, { withFileTypes: true });
@@ -72,7 +83,6 @@ async function getFolderOutput(folderPath) {
         return undefined;
     });
 }
-exports.getFolderOutput = getFolderOutput;
 // API
 /**
  * @param entryPath Relative to cwd
@@ -90,5 +100,4 @@ async function programOutput(entryPath) {
         return value;
     });
 }
-exports.programOutput = programOutput;
 //# sourceMappingURL=output.js.map

package/build/src/json.js

@@ -15,13 +15,23 @@ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (
 }) : function(o, v) {
     o["default"] = v;
 });
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
-};
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 const path = __importStar(require("path"));
 const process = __importStar(require("process"));

package/build/src/ui-server/ui-server.d.ts

@@ -1,3 +1,2 @@
-/// <reference types="node" />
 import * as http from "http";
 export declare function createUiServer(combinedOutputsJson: string): http.Server;

package/build/src/ui-server/ui-server.js

@@ -15,15 +15,25 @@ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (
 }) : function(o, v) {
     o["default"] = v;
 });
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
-};
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createUiServer = void 0;
+exports.createUiServer = createUiServer;
 const fs_1 = require("fs");
 const http = __importStar(require("http"));
 const path = __importStar(require("path"));
@@ -47,7 +57,6 @@ function createUiServer(combinedOutputsJson) {
         res.end();
     });
 }
-exports.createUiServer = createUiServer;
 function cached(res) {
     res.setHeader("Cache-Control", "max-age=365000000; immutable");
 }

package/build/src/util/util.d.ts

@@ -1,4 +1,3 @@
-export declare function countNotAtTheEnds<T>(arr: T[], count: (elem: T) => boolean): number;
 export declare function doesNotThrow<T>(promise: Promise<T>): Promise<boolean>;
 /**
  * Builds an object from a list of keys whose values are based on the key itself,
@@ -17,7 +16,6 @@ export declare function keysToAsyncValues<K extends keyof any, V>(keys: K[], toV
 export declare function createObjectOfPromisedValues<I, K extends keyof any, V>(inputs: I[], toKey: (input: I) => K, toMaybePromise: (input: I) => Promise<V> | undefined): Promise<Record<K, V>>;
 export declare function nonNaN(num: number, fallback: number): number;
 export declare function repeat(str: string, times: number): string;
-export declare function toPromise<T, E>(action: (callback: (err: E, successData: T) => void) => void, errorTransformer?: (err: E) => Error): Promise<T>;
 export declare class Unreachable extends Error {
     constructor(reason: string);
 }

package/build/src/util/util.js

@@ -1,19 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Unreachable = exports.toPromise = exports.repeat = exports.nonNaN = exports.createObjectOfPromisedValues = exports.keysToAsyncValues = exports.doesNotThrow = exports.countNotAtTheEnds = void 0;
-function countNotAtTheEnds(arr, count) {
-    if (arr.length <= 2) {
-        return 0;
-    }
-    let tot = 0;
-    for (let i = 1; i < arr.length - 2; i++) {
-        if (count(arr[i])) {
-            tot += 1;
-        }
-    }
-    return tot;
-}
-exports.countNotAtTheEnds = countNotAtTheEnds;
+exports.Unreachable = void 0;
+exports.doesNotThrow = doesNotThrow;
+exports.keysToAsyncValues = keysToAsyncValues;
+exports.createObjectOfPromisedValues = createObjectOfPromisedValues;
+exports.nonNaN = nonNaN;
+exports.repeat = repeat;
 async function doesNotThrow(promise) {
     try {
         await promise;
@@ -23,7 +15,6 @@ async function doesNotThrow(promise) {
         return false;
     }
 }
-exports.doesNotThrow = doesNotThrow;
 /**
  * Builds an object from a list of keys whose values are based on the key itself,
  * but where that value is produced asynchronously.
@@ -43,7 +34,6 @@ async function keysToAsyncValues(keys, toValue) {
     await Promise.all(promises);
     return output;
 }
-exports.keysToAsyncValues = keysToAsyncValues;
 /**
  * Builds an object from a list of input items.
  * The keys and values are derived from the input item,
@@ -70,14 +60,12 @@ async function createObjectOfPromisedValues(inputs, toKey, toMaybePromise) {
     await Promise.all(promises);
     return output;
 }
-exports.createObjectOfPromisedValues = createObjectOfPromisedValues;
 function nonNaN(num, fallback) {
     if (Number.isNaN(num)) {
         return fallback;
     }
     return num;
 }
-exports.nonNaN = nonNaN;
 function repeat(str, times) {
     let res = "";
     for (let i = 0; i < times; i++) {
@@ -85,20 +73,6 @@ function repeat(str, times) {
     }
     return res;
 }
-exports.repeat = repeat;
-function toPromise(action, errorTransformer) {
-    return new Promise((resolve, reject) => {
-        action((err, successData) => {
-            if (err) {
-                reject(errorTransformer ? errorTransformer(err) : err);
-            }
-            else {
-                resolve(successData);
-            }
-        });
-    });
-}
-exports.toPromise = toPromise;
 class Unreachable extends Error {
     constructor(reason) {
         super("Unreachable branch.\n" + reason);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cognitive-complexity-ts",
-  "version": "0.6.4",
+  "version": "0.7.0",
   "description": "",
   "keywords": [
     "typescript",
@@ -45,22 +45,19 @@
   "homepage": "https://github.com/Deskbot/Cognitive-Complexity-TS#readme",
   "repository": "https://github.com/Deskbot/Cognitive-Complexity-TS",
   "dependencies": {
-    "js-beautify": "^1.11.0",
-    "minimist": "^1.2.5",
-    "open": "^7.1.0",
-    "source-map-support": "^0.5.19",
-    "typescript": "^5.2.2"
+    "js-beautify": "^1.15.4",
+    "minimist": "^1.2.8",
+    "open": "^11.0.0",
+    "source-map-support": "^0.5.21",
+    "typescript": "^5.9.3"
   },
   "devDependencies": {
-    "@types/deep-diff": "^1.0.0",
-    "@types/glob": "^7.1.1",
-    "@types/js-beautify": "^1.8.2",
-    "@types/minimist": "^1.2.0",
-    "@types/node": "^12.12.6",
-    "@types/tempfile": "^3.0.0",
+    "@types/deep-diff": "^1.0.5",
+    "@types/glob": "^9.0.0",
+    "@types/js-beautify": "^1.14.3",
+    "@types/minimist": "^1.2.5",
+    "@types/node": "^24.10.4",
     "deep-diff": "^1.0.2",
-    "glob": "^7.1.6",
-    "json-stream": "^1.0.0",
-    "tempfile": "^3.0.0"
+    "glob": "^13.0.0"
   }
 }

package/ui/README.md

@@ -1,26 +0,0 @@
-# UI
-
-Why is it written like this?
-
-I want the value of componentised web development without a heavy framework. The UI is not so complicated that it requires html to change once written. The style does need to be slightly dynamic, which can be accomplished through the simple traditional DOM API.
-
-Although frameworks allow for declarative code that is very short and readable, without transpilation it is inherently inefficient and would require the use of libraries with large memory footprints and speed-limiting virtual-DOM.
-
-* Responsiveness of user-interfaces matters to users.
-* RAM is valuable and programmers use a lot of it. A tool to help developers shouldn't take too much of it.
-
-I am experimenting with ways of writing simple, well-organised, performant web UI code. I think it is important for this project because people may wish to look at an entire project at once.
-
-I'm not entirely happy with certain aspects of this code, but it has been a learning experience. A lot of this turned out rather ad-hoc instead of like a framework, but I know how I would like things to look; the time that would be required to get to that point isn't worth it.
-
-## Guiding Principles
-
-* In reality UI is mutable and simple changes are simple to do in modern JavaScript.
-* Components can be functional or stateful. Following the well-established principles of keeping components small and simple, means stateful components should not be too difficult to manage.
-* Each stateful component should expose a single DOM element that has any number of children. Components can not change the DOM of another component, except by parenting their exposed DOM, or by adding a class to the exposed DOM that only affects its positioning (e.g. flex attributes). This allows the DOM of a component to be slotted in and out of the page, while not interfering with its internal behaviour and state.
-    * Note that document fragments can not be exposed by components because attaching the fragment to the dom re-parents the fragment's children.
-    * Functional components can return arrays of components or DOM.
-* Components should be agnostic about their positioning. A component's creator should choose its position in the page if any.
-    * Flex CSS properties rely on groups of elements having properties that work together in specific ways. It makes much more sense for an element that has a `display` of `flex` or `inline-flex` to enforce the flex properties of its children than to give components general rules about how they should be sized if they happen to be put in a flex container.
-* Other CSS for a component should be discoverable from the component code. This is achieved with lazy CSS imports being added when a component module is loaded.
-* Stateful components should be rendered on construction to ensure that they are rendered correctly with all usages. Each method that alters the state of a component should also trigger a re-render. Although it should be avoided, it is ok for multiple re-renders to take place where a single one could be achieved and would be more efficient, if the code is still performant.