@nielspeter/eess-ts 0.1.0

package/dist/helpers/complexity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"complexity.d.ts","sourceRoot":"","sources":["../../src/helpers/complexity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,IAAI,EAAE,MAAM,UAAU,CAAA;AAC3C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAA;AAsBhD;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,IAAI,GAAG,SAAS,GAAG,MAAM,CAoBnE;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAE9C;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,gBAAgB,GAAG,MAAM,CAEzD"}

package/dist/helpers/complexity.js

@@ -0,0 +1,64 @@
+import { SyntaxKind, Node } from 'ts-morph';
+/** Decision-point SyntaxKinds that increment cyclomatic complexity */
+const DECISION_KINDS = new Set([
+    SyntaxKind.IfStatement,
+    SyntaxKind.ConditionalExpression,
+    SyntaxKind.ForStatement,
+    SyntaxKind.ForInStatement,
+    SyntaxKind.ForOfStatement,
+    SyntaxKind.WhileStatement,
+    SyntaxKind.DoStatement,
+    SyntaxKind.CatchClause,
+    SyntaxKind.CaseClause,
+]);
+/** Logical operator tokens that add branching */
+const LOGICAL_OPERATORS = new Set([
+    SyntaxKind.AmpersandAmpersandToken, // &&
+    SyntaxKind.BarBarToken, // ||
+    SyntaxKind.QuestionQuestionToken, // ??
+]);
+/**
+ * Calculate cyclomatic complexity (McCabe) for a function body.
+ *
+ * Accepts the body Node directly (from ArchFunction.getBody(),
+ * MethodDeclaration.getBody(), etc.).
+ *
+ * Complexity = 1 + number of decision points.
+ * Returns 1 for an undefined/empty body (one path through).
+ */
+export function cyclomaticComplexity(body) {
+    if (!body)
+        return 1;
+    let complexity = 1;
+    for (const descendant of body.getDescendants()) {
+        if (DECISION_KINDS.has(descendant.getKind())) {
+            complexity++;
+        }
+        // Count logical operators in binary expressions
+        if (Node.isBinaryExpression(descendant)) {
+            const opKind = descendant.getOperatorToken().getKind();
+            if (LOGICAL_OPERATORS.has(opKind)) {
+                complexity++;
+            }
+        }
+    }
+    return complexity;
+}
+/**
+ * Count lines spanned by a node (from first line to last line, inclusive).
+ *
+ * This is a "span lines" count — it includes blank lines and comments
+ * within the node's range. This is consistent with how editors report
+ * function/class length, and avoids the fragility of text-based
+ * comment stripping.
+ */
+export function linesOfCode(node) {
+    return node.getEndLineNumber() - node.getStartLineNumber() + 1;
+}
+/**
+ * Count the number of methods on a class.
+ */
+export function methodCount(cls) {
+    return cls.getMethods().length;
+}
+//# sourceMappingURL=complexity.js.map

package/dist/helpers/complexity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"complexity.js","sourceRoot":"","sources":["../../src/helpers/complexity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,UAAU,CAAA;AAG3C,sEAAsE;AACtE,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC;IAC7B,UAAU,CAAC,WAAW;IACtB,UAAU,CAAC,qBAAqB;IAChC,UAAU,CAAC,YAAY;IACvB,UAAU,CAAC,cAAc;IACzB,UAAU,CAAC,cAAc;IACzB,UAAU,CAAC,cAAc;IACzB,UAAU,CAAC,WAAW;IACtB,UAAU,CAAC,WAAW;IACtB,UAAU,CAAC,UAAU;CACtB,CAAC,CAAA;AAEF,iDAAiD;AACjD,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAAC;IAChC,UAAU,CAAC,uBAAuB,EAAE,KAAK;IACzC,UAAU,CAAC,WAAW,EAAE,KAAK;IAC7B,UAAU,CAAC,qBAAqB,EAAE,KAAK;CACxC,CAAC,CAAA;AAEF;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAsB;IACzD,IAAI,CAAC,IAAI;QAAE,OAAO,CAAC,CAAA;IAEnB,IAAI,UAAU,GAAG,CAAC,CAAA;IAElB,KAAK,MAAM,UAAU,IAAI,IAAI,CAAC,cAAc,EAAE,EAAE,CAAC;QAC/C,IAAI,cAAc,CAAC,GAAG,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC;YAC7C,UAAU,EAAE,CAAA;QACd,CAAC;QAED,gDAAgD;QAChD,IAAI,IAAI,CAAC,kBAAkB,CAAC,UAAU,CAAC,EAAE,CAAC;YACxC,MAAM,MAAM,GAAG,UAAU,CAAC,gBAAgB,EAAE,CAAC,OAAO,EAAE,CAAA;YACtD,IAAI,iBAAiB,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;gBAClC,UAAU,EAAE,CAAA;YACd,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,UAAU,CAAA;AACnB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,IAAU;IACpC,OAAO,IAAI,CAAC,gBAAgB,EAAE,GAAG,IAAI,CAAC,kBAAkB,EAAE,GAAG,CAAC,CAAA;AAChE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,GAAqB;IAC/C,OAAO,GAAG,CAAC,UAAU,EAAE,CAAC,MAAM,CAAA;AAChC,CAAC"}

package/dist/helpers/matchers.d.ts

@@ -0,0 +1,206 @@
+import { Node, SyntaxKind } from 'ts-morph';
+/**
+ * A matcher that tests whether a ts-morph AST node matches a specific pattern.
+ *
+ * Matchers are created by helper functions (call, access, newExpr, expression)
+ * and consumed by body analysis conditions (contain, notContain, useInsteadOf).
+ */
+export interface ExpressionMatcher {
+    /** Human-readable description for violation messages */
+    readonly description: string;
+    /**
+     * The SyntaxKind(s) this matcher targets.
+     * Used to narrow the AST traversal — only nodes of these kinds are tested.
+     * If undefined, all descendant nodes are tested (used by expression()).
+     */
+    readonly syntaxKinds?: SyntaxKind[];
+    /**
+     * Test whether a single AST node matches this pattern.
+     *
+     * Precondition: the node's kind is one of `syntaxKinds` (if specified).
+     * The condition layer enforces this — matchers can assume the kind is correct.
+     */
+    matches(node: Node): boolean;
+}
+/**
+ * Match a CallExpression by function/method name.
+ *
+ * Matches against `CallExpression.getExpression().getText()` after
+ * normalizing optional chaining.
+ *
+ * @param nameOrRegex - Exact name (e.g. 'parseInt', 'this.normalizeCount')
+ *                      or regex for flexible matching.
+ *
+ * @example
+ * call('parseInt')                    // matches parseInt(x)
+ * call('this.normalizeCount')         // matches this.normalizeCount(x) AND this?.normalizeCount(x)
+ * call(/^console\./)                  // matches console.log, console.warn, etc.
+ */
+export declare function call(nameOrRegex: string | RegExp): ExpressionMatcher;
+/**
+ * Match a PropertyAccessExpression by the dotted chain.
+ *
+ * Matches against `PropertyAccessExpression.getText()` after normalizing
+ * optional chaining. Useful for detecting direct property access patterns
+ * like `process.env`, `this.db`, `window.location`.
+ *
+ * @param chain - Exact dotted chain (e.g. 'process.env') or regex.
+ *
+ * @example
+ * access('process.env')               // matches process.env.FOO (the inner access)
+ * access(/^this\.db/)                 // matches this.db, this.db.query, etc.
+ */
+export declare function access(chain: string | RegExp): ExpressionMatcher;
+/**
+ * Match a NewExpression by constructor name.
+ *
+ * Matches against `NewExpression.getExpression().getText()`.
+ * The PoC confirmed this correctly distinguishes 'Error' from 'DomainError'.
+ *
+ * @param nameOrRegex - Exact constructor name or regex.
+ *
+ * @example
+ * newExpr('Error')                    // matches new Error(...) but NOT new DomainError(...)
+ * newExpr('DomainError')              // matches new DomainError(...)
+ * newExpr(/Error$/)                   // matches new Error, new DomainError, new TypeError, etc.
+ */
+export declare function newExpr(nameOrRegex: string | RegExp): ExpressionMatcher;
+/**
+ * Escape hatch: match any node whose getText() contains or matches the given pattern.
+ *
+ * This is intentionally broad and should be used sparingly. It walks ALL
+ * descendant nodes and checks getText() against the pattern. A runtime
+ * console.warn is emitted the first time expression() is used, encouraging
+ * users to prefer call/access/newExpr where possible.
+ *
+ * @param textOrRegex - Substring to search for (string) or regex pattern.
+ *
+ * @example
+ * expression('eval')                  // matches any node containing 'eval'
+ * expression(/document\.write/)       // matches document.write calls
+ */
+export declare function expression(textOrRegex: string | RegExp): ExpressionMatcher;
+export declare function property(name: string | RegExp, value?: boolean | number | string | RegExp): ExpressionMatcher;
+/**
+ * Default stub/deferred-work patterns found in comments.
+ * Matches common markers (see regex) and phrases like
+ * "not implemented" or "coming soon".
+ *
+ * Exported as a constant for use with `comment()`. Users can pass
+ * their own RegExp to `comment()` for narrower matching.
+ */
+export declare const STUB_PATTERNS: RegExp;
+/**
+ * Match comments attached to AST nodes.
+ *
+ * Unlike other matchers that test AST nodes, this matcher tests the
+ * leading and trailing comment ranges of each node. It uses
+ * `syntaxKinds: undefined` so the broad traversal path visits every node,
+ * and `matches(node)` checks that node's comment ranges.
+ *
+ * A Set tracks matched comment positions to avoid duplicates (the same
+ * comment may be visited as leading trivia of multiple nested nodes).
+ *
+ * @param pattern - String substring or RegExp to test against comment text.
+ *
+ * @example
+ * comment(/HACK/)                     // matches hack marker comments
+ * comment(STUB_PATTERNS)              // matches all common stub markers
+ * comment('HACK')                     // matches hack comments
+ */
+export declare function comment(pattern: string | RegExp): ExpressionMatcher;
+/**
+ * Match a JSX element by tag name.
+ *
+ * Targets `JsxElement` (has children) and `JsxSelfClosingElement` (no children).
+ * This is a **tag-only** matcher — it cannot check attributes. Use the
+ * `jsxElements()` entry point for attribute-level rules.
+ *
+ * @param tagOrRegex - Exact tag name (e.g. 'div', 'Button') or regex.
+ *
+ * @example
+ * jsxElement('div')                    // matches <div>...</div> and <div />
+ * jsxElement('Button')                 // matches <Button>...</Button>
+ * jsxElement(/^motion\./)              // matches <motion.div>, <motion.span>, etc.
+ */
+export declare function jsxElement(tagOrRegex: string | RegExp): ExpressionMatcher;
+/**
+ * Match hardcoded JSX text content — the children of JSX elements.
+ *
+ * Where {@link jsxElement} matches elements by tag and the `jsxElements()`
+ * entry point handles attribute values, this matcher covers the remaining
+ * gap: literal text rendered as element children. Composes with
+ * `notContain()` for i18n-style rules ("no hardcoded user-facing text").
+ *
+ * Matches:
+ * - `JsxText` nodes with non-whitespace content (`<button>Save</button>`).
+ * - `JsxExpression` wrapping a bare string literal (`<div>{"Save"}</div>`)
+ *   or a no-substitution template (`` <div>{`Save`}</div> ``) — these render
+ *   identically to plain text and would otherwise be a trivial bypass.
+ *
+ * Does NOT match: inter-element whitespace, `{expr}` wrapping an identifier
+ * or call (`<div>{t("save")}</div>`), templates with substitution
+ * (`` <div>{`Hi ${name}`}</div> ``), or attribute values whether braced or
+ * quoted (`title={"Save"}`, `title="Save"`) — those belong to the
+ * `jsxElements()` entry point. No letter-presence filter is baked in —
+ * `<div>123</div>` matches; the matcher takes no options, so to narrow which
+ * text is flagged, scope the rule with folder/file predicates or
+ * `.excluding(...)`. Note: text inside translation wrappers like `<Trans>`
+ * also matches — scope those out the same way if your i18n setup uses them.
+ *
+ * @example
+ * modules(p)
+ *   .that()
+ *   .resideInFolder('src/components/**')
+ *   .should()
+ *   .notContain(jsxText())
+ *   .because('User-facing text must go through t()')
+ *   .check()
+ */
+export declare function jsxText(): ExpressionMatcher;
+/**
+ * Options for the `typeAssertion()` matcher.
+ */
+export interface TypeAssertionOptions {
+    /**
+     * Whether to allow `as const` in user code (default: true).
+     *
+     * | Option                 | Matcher matches `as const`? | With `notContain()` — is `as const` allowed in code? |
+     * | ---------------------- | --------------------------- | ---------------------------------------------------- |
+     * | default (`true`)       | no                          | yes — idiomatic literal preservation                 |
+     * | `{ allowConst: false }` | yes                         | no — bans ALL `as` expressions                      |
+     *
+     * Does NOT affect angle-bracket assertions (`<Type>value`) — those can't
+     * express `as const` and are always matched.
+     */
+    readonly allowConst?: boolean;
+}
+/**
+ * Match type assertion expressions — both `as Type` and the legacy
+ * angle-bracket `<Type>value` form.
+ *
+ * By default, `as const` is excluded from matches (it narrows types rather
+ * than widening them, so it's idiomatic for literal preservation). The
+ * `allowConst` option does not affect angle-bracket assertions — those
+ * can't express `as const` and are always matched.
+ *
+ * Does NOT match `satisfies` expressions — those are validation, not
+ * assertions, and should not be banned.
+ *
+ * @example
+ * // Allow `as const` in user code (default)
+ * classes(p).should().notContain(typeAssertion()).check()
+ *
+ * @example
+ * // Ban `as const` too — no `as` expressions of any kind
+ * modules(p).should().notContain(typeAssertion({ allowConst: false })).check()
+ */
+export declare function typeAssertion(options?: TypeAssertionOptions): ExpressionMatcher;
+/**
+ * Match `!` non-null assertion expressions.
+ *
+ * @example
+ * functions(p).should().notContain(nonNullAssertion()).check()
+ */
+export declare function nonNullAssertion(): ExpressionMatcher;
+//# sourceMappingURL=matchers.d.ts.map

package/dist/helpers/matchers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"matchers.d.ts","sourceRoot":"","sources":["../../src/helpers/matchers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,UAAU,EAAqB,MAAM,UAAU,CAAA;AAE9D;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,wDAAwD;IACxD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAE5B;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,UAAU,EAAE,CAAA;IAEnC;;;;;OAKG;IACH,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAA;CAC7B;AAaD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,iBAAiB,CAqBpE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,iBAAiB,CAqBhE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,OAAO,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,iBAAiB,CAqBvE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,iBAAiB,CAgC1E;AAsDD,wBAAgB,QAAQ,CACtB,IAAI,EAAE,MAAM,GAAG,MAAM,EACrB,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GACzC,iBAAiB,CAgBnB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,QACsE,CAAA;AAEhG;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,iBAAiB,CAoCnE;AAeD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,iBAAiB,CAoBzE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,OAAO,IAAI,iBAAiB,CAwB3C;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAA;CAC9B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAAC,OAAO,CAAC,EAAE,oBAAoB,GAAG,iBAAiB,CAoB/E;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,IAAI,iBAAiB,CAQpD"}