codemetrics-ai 0.2.0

package/dist/evidence.schema.v3.json

@@ -0,0 +1,444 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/sean-m-cooper/CodeMetrics.AI/shared/scorecard-schema/evidence.schema.v3.json",
+  "title": "CodeMetrics.AI Evidence v3",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "generatedAtUtc",
+    "tool",
+    "subject",
+    "filters",
+    "population",
+    "dimensions",
+    "analysis"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": {
+      "const": 3
+    },
+    "generatedAtUtc": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "tool": {
+      "type": "object",
+      "required": [
+        "name",
+        "version",
+        "ecosystem"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "version": {
+          "type": "string",
+          "minLength": 1
+        },
+        "ecosystem": {
+          "enum": [
+            "dotnet",
+            "javascript-typescript",
+            "python",
+            "rust"
+          ]
+        }
+      }
+    },
+    "subject": {
+      "type": "object",
+      "required": [
+        "root",
+        "entryPoint"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "root": {
+          "type": "string",
+          "minLength": 1
+        },
+        "entryPoint": {
+          "type": "string",
+          "minLength": 1
+        },
+        "name": {
+          "type": "string"
+        },
+        "variant": {
+          "type": "string"
+        }
+      }
+    },
+    "filters": {
+      "type": "object",
+      "required": [
+        "totalUnits",
+        "analyzedUnits",
+        "skipped"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "totalUnits": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "analyzedUnits": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "skipped": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "name",
+              "reason"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "name": {
+                "type": "string",
+                "minLength": 1
+              },
+              "reason": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          }
+        }
+      }
+    },
+    "population": {
+      "type": "object",
+      "required": [
+        "types",
+        "members"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "types": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "members": {
+          "type": "integer",
+          "minimum": 0
+        }
+      }
+    },
+    "dimensions": {
+      "type": "object",
+      "required": [
+        "codeQuality",
+        "maintainability",
+        "errorHandling",
+        "performanceAsync",
+        "security",
+        "testing",
+        "documentation",
+        "dependencyManagement",
+        "architecture"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "codeQuality": {
+          "$ref": "#/$defs/dimensionResult"
+        },
+        "maintainability": {
+          "$ref": "#/$defs/dimensionResult"
+        },
+        "errorHandling": {
+          "$ref": "#/$defs/dimensionResult"
+        },
+        "performanceAsync": {
+          "$ref": "#/$defs/dimensionResult"
+        },
+        "security": {
+          "$ref": "#/$defs/dimensionResult"
+        },
+        "testing": {
+          "$ref": "#/$defs/dimensionResult"
+        },
+        "documentation": {
+          "$ref": "#/$defs/dimensionResult"
+        },
+        "dependencyManagement": {
+          "$ref": "#/$defs/dimensionResult"
+        },
+        "architecture": {
+          "$ref": "#/$defs/dimensionResult"
+        }
+      }
+    },
+    "analysis": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "status",
+        "ruleset",
+        "calibration",
+        "configurationFingerprint",
+        "diagnostics",
+        "suppressions"
+      ],
+      "properties": {
+        "status": {
+          "enum": [
+            "complete",
+            "incomplete"
+          ]
+        },
+        "ruleset": {
+          "type": "string",
+          "minLength": 1
+        },
+        "calibration": {
+          "enum": [
+            "baseline",
+            "uncalibrated",
+            "calibrated"
+          ]
+        },
+        "configurationFingerprint": {
+          "type": "string",
+          "minLength": 1
+        },
+        "diagnostics": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "kind",
+              "message"
+            ],
+            "properties": {
+              "kind": {
+                "type": "string"
+              },
+              "message": {
+                "type": "string"
+              },
+              "project": {
+                "type": "string"
+              }
+            },
+            "additionalProperties": false
+          }
+        },
+        "suppressions": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "file",
+              "line",
+              "categories",
+              "status"
+            ],
+            "properties": {
+              "file": {
+                "type": "string"
+              },
+              "line": {
+                "type": "integer",
+                "minimum": 1
+              },
+              "categories": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "reason": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "status": {
+                "enum": [
+                  "declared",
+                  "applied"
+                ]
+              }
+            },
+            "additionalProperties": false
+          }
+        },
+        "runId": {
+          "type": "string",
+          "format": "uuid"
+        },
+        "auditId": {
+          "type": "string",
+          "format": "uuid"
+        }
+      }
+    }
+  },
+  "$defs": {
+    "dimensionResult": {
+      "type": "object",
+      "required": [
+        "status",
+        "basis",
+        "findings"
+      ],
+      "properties": {
+        "status": {
+          "enum": [
+            "scored",
+            "skipped",
+            "failed"
+          ]
+        },
+        "score": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 10
+        },
+        "basis": {
+          "type": "string",
+          "minLength": 1
+        },
+        "findings": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/finding"
+          }
+        },
+        "scope": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "id",
+            "coverage",
+            "includes",
+            "excludes"
+          ],
+          "properties": {
+            "id": {
+              "type": "string",
+              "minLength": 1
+            },
+            "coverage": {
+              "enum": [
+                "partial",
+                "unsupported"
+              ]
+            },
+            "includes": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1
+              }
+            },
+            "excludes": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          }
+        }
+      },
+      "additionalProperties": true,
+      "if": {
+        "properties": {
+          "status": {
+            "const": "scored"
+          }
+        },
+        "required": [
+          "status"
+        ]
+      },
+      "then": {
+        "required": [
+          "score"
+        ]
+      },
+      "else": {
+        "not": {
+          "required": [
+            "score"
+          ]
+        }
+      }
+    },
+    "finding": {
+      "type": "object",
+      "required": [
+        "category",
+        "severity",
+        "message",
+        "ruleId",
+        "fingerprint",
+        "confidence",
+        "observations"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "category": {
+          "type": "string",
+          "minLength": 1
+        },
+        "severity": {
+          "enum": [
+            "info",
+            "warning",
+            "error"
+          ]
+        },
+        "file": {
+          "type": "string"
+        },
+        "line": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "project": {
+          "type": "string"
+        },
+        "type": {
+          "type": "string"
+        },
+        "member": {
+          "type": "string"
+        },
+        "package": {
+          "type": "string"
+        },
+        "confidence": {
+          "enum": [
+            "high",
+            "medium",
+            "low"
+          ]
+        },
+        "message": {
+          "type": "string",
+          "minLength": 1
+        },
+        "ruleId": {
+          "type": "string",
+          "minLength": 1
+        },
+        "fingerprint": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{64}$"
+        },
+        "observations": {
+          "type": "object"
+        }
+      }
+    }
+  }
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { defaultEvidencePath, defaultMetricsPath, dimensionKeys, ecosystemId, metricsCsvHeader, type DimensionKey, } from "./scorecard-contract.js";
+export { analyze } from "./analyzer.js";
+export { compare, gate, sarif, validateEvidence, readEvidence } from "./evidence-tools.js";
+export type { Evidence, Finding, Dimension } from "./evidence.js";
+export { readCompatibleEvidence, inspectEvidence, type LegacyEvidence } from "./evidence-reader.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export { defaultEvidencePath, defaultMetricsPath, dimensionKeys, ecosystemId, metricsCsvHeader, } from "./scorecard-contract.js";
+export { analyze } from "./analyzer.js";
+export { compare, gate, sarif, validateEvidence, readEvidence } from "./evidence-tools.js";
+export { readCompatibleEvidence, inspectEvidence } from "./evidence-reader.js";

package/dist/io.d.ts

@@ -0,0 +1,2 @@
+export declare function write(file: string, value: unknown): void;
+export declare function distinctOutputs(inputs: (string | undefined)[], outputs: (string | undefined)[]): void;

package/dist/io.js

@@ -0,0 +1,21 @@
+import fs from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+export function write(file, value) {
+    fs.mkdirSync(path.dirname(path.resolve(file)), { recursive: true });
+    const temporary = file + "." + randomUUID() + ".tmp";
+    try {
+        fs.writeFileSync(temporary, typeof value === "string" ? value : JSON.stringify(value, null, 2) + "\n");
+        fs.renameSync(temporary, file);
+    }
+    finally {
+        if (fs.existsSync(temporary))
+            fs.unlinkSync(temporary);
+    }
+}
+export function distinctOutputs(inputs, outputs) {
+    const normalize = (file) => process.platform === "win32" ? path.resolve(file).toLowerCase() : path.resolve(file);
+    const targets = outputs.filter((file) => !!file).map(normalize);
+    if (new Set(targets).size !== targets.length || inputs.some(file => file && targets.includes(normalize(file))))
+        throw new Error("Output paths must be distinct and must not overwrite inputs.");
+}

package/dist/metrics.d.ts

@@ -0,0 +1,26 @@
+import ts from "typescript";
+import { type Finding } from "./evidence.js";
+export interface Metric {
+    project: string;
+    file: string;
+    type: string;
+    member: string;
+    kind: "function" | "component" | "hook" | "method";
+    line: number;
+    complexity: number;
+    sourceLines: number;
+    executableLines: number;
+    halsteadVolume: number;
+    maintainabilityIndex: number;
+    coupling: number;
+    inheritance: number;
+}
+export declare function maintainability(volume: number, complexity: number, lines: number): number;
+export declare function analyzeFile(source: ts.SourceFile, checker: ts.TypeChecker, project: string, root: string): {
+    metrics: Metric[];
+    findings: {
+        dimension: "codeQuality" | "performanceAsync";
+        finding: Finding;
+    }[];
+    reactSupported: boolean;
+};

package/dist/metrics.js

@@ -0,0 +1,153 @@
+import path from "node:path";
+import ts from "typescript";
+import { hash } from "./evidence.js";
+function isFunction(node) {
+    return ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node) || ts.isArrowFunction(node) ||
+        ts.isMethodDeclaration(node) || ts.isConstructorDeclaration(node) || ts.isGetAccessorDeclaration(node) || ts.isSetAccessorDeclaration(node);
+}
+function nameOf(node, source) {
+    if (node.name)
+        return node.name.getText(source);
+    if (ts.isConstructorDeclaration(node))
+        return "constructor";
+    if (ts.isVariableDeclaration(node.parent) || ts.isPropertyAssignment(node.parent))
+        return node.parent.name.getText(source);
+    if (ts.isCallExpression(node.parent))
+        return `${node.parent.expression.getText(source)}:callback${node.parent.arguments.indexOf(node)}`;
+    return "anonymous";
+}
+function ownVisit(node, visit) {
+    if (isFunction(node) || ts.isTypeNode(node) || ts.isInterfaceDeclaration(node) || ts.isTypeAliasDeclaration(node))
+        return;
+    visit(node);
+    ts.forEachChild(node, child => ownVisit(child, visit));
+}
+export function maintainability(volume, complexity, lines) {
+    return Math.round(Math.max(0, (171 - 5.2 * Math.log(Math.max(volume, 1)) - 0.23 * complexity - 16.2 * Math.log(Math.max(lines, 1))) * 100 / 171));
+}
+export function analyzeFile(source, checker, project, root) {
+    const file = path.relative(root, source.fileName).replaceAll("\\", "/");
+    const metrics = [];
+    const findings = [];
+    const importCount = new Set(source.statements.filter(ts.isImportDeclaration).map(node => node.moduleSpecifier.getText(source))).size;
+    const identities = new Map();
+    function emit(category, dimension, node, member, message, observations, confidence = "high") {
+        const ruleId = `javascript-typescript/${dimension}/${category}`;
+        const identity = `${ruleId}|${file}|${project}|${member}`;
+        const occurrence = identities.get(identity) ?? 0;
+        identities.set(identity, occurrence + 1);
+        findings.push({ dimension, finding: { category, ruleId, fingerprint: hash(`${identity}|${occurrence}`),
+                severity: "warning", confidence, file, line: source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1,
+                project, member, message, observations } });
+    }
+    function visit(node, parentName = "") {
+        if (isFunction(node) && node.body) {
+            const name = nameOf(node, source);
+            const member = parentName ? `${parentName}/${name}` : name;
+            const parentClass = ts.isClassDeclaration(node.parent) || ts.isClassExpression(node.parent) ? node.parent : undefined;
+            let complexity = 1, executableLines = 0, hasJsx = false;
+            ownVisit(node.body, child => {
+                if (ts.isIfStatement(child) || ts.isForStatement(child) || ts.isForInStatement(child) || ts.isForOfStatement(child) ||
+                    ts.isWhileStatement(child) || ts.isDoStatement(child) || ts.isCatchClause(child) || ts.isCaseClause(child) || ts.isConditionalExpression(child))
+                    complexity++;
+                if (ts.isBinaryExpression(child) && [ts.SyntaxKind.AmpersandAmpersandToken, ts.SyntaxKind.BarBarToken, ts.SyntaxKind.QuestionQuestionToken].includes(child.operatorToken.kind))
+                    complexity++;
+                if (ts.isStatement(child) && !ts.isBlock(child) && !ts.isEmptyStatement(child))
+                    executableLines++;
+                if (ts.isJsxElement(child) || ts.isJsxSelfClosingElement(child) || ts.isJsxFragment(child))
+                    hasJsx = true;
+                if (ts.isCallExpression(child)) {
+                    const symbol = checker.getSymbolAtLocation(ts.isPropertyAccessExpression(child.expression) ? child.expression.name : child.expression);
+                    const declarations = symbol?.declarations ?? [];
+                    const reactHook = declarations.some(declaration => {
+                        let cursor = declaration;
+                        while (cursor && !ts.isImportDeclaration(cursor))
+                            cursor = cursor.parent;
+                        return cursor && ts.isStringLiteral(cursor.moduleSpecifier) && cursor.moduleSpecifier.text === "react";
+                    });
+                    const hookName = declarations.find(ts.isImportSpecifier);
+                    const calledName = hookName ? (hookName.propertyName ?? hookName.name).text : ts.isPropertyAccessExpression(child.expression) ? child.expression.name.text : "";
+                    const namespaceSymbol = ts.isPropertyAccessExpression(child.expression) ? checker.getSymbolAtLocation(child.expression.expression) : undefined;
+                    const reactNamespace = namespaceSymbol?.declarations?.some(declaration => {
+                        let cursor = declaration;
+                        while (cursor && !ts.isImportDeclaration(cursor))
+                            cursor = cursor.parent;
+                        return cursor && ts.isStringLiteral(cursor.moduleSpecifier) && cursor.moduleSpecifier.text === "react";
+                    });
+                    if ((reactHook || reactNamespace) && /^use[A-Z]/.test(calledName)) {
+                        let ancestor = child.parent;
+                        while (ancestor && ancestor !== node.body) {
+                            if (ts.isIfStatement(ancestor) || ts.isConditionalExpression(ancestor) || ts.isForStatement(ancestor) || ts.isForOfStatement(ancestor) || ts.isForInStatement(ancestor) || ts.isWhileStatement(ancestor) || ts.isDoStatement(ancestor) ||
+                                ts.isBinaryExpression(ancestor) && [ts.SyntaxKind.AmpersandAmpersandToken, ts.SyntaxKind.BarBarToken, ts.SyntaxKind.QuestionQuestionToken].includes(ancestor.operatorToken.kind)) {
+                                emit("conditionalHook", "performanceAsync", child, member, `${calledName} is called within a conditional or loop.`, { hook: calledName });
+                                break;
+                            }
+                            ancestor = ancestor.parent;
+                        }
+                        if (["useEffect", "useLayoutEffect"].includes(calledName)) {
+                            const callback = child.arguments[0];
+                            if (callback && isFunction(callback) && callback.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.AsyncKeyword))
+                                emit("asyncEffectCallback", "performanceAsync", child, member, "An effect callback is async and returns a Promise instead of cleanup or undefined.", { hook: calledName });
+                            if (child.arguments.length < 2)
+                                emit("effectWithoutDependencies", "performanceAsync", child, member, "Effect runs after every render; verify that this is intentional.", { hook: calledName }, "low");
+                        }
+                    }
+                }
+            });
+            if (!ts.isBlock(node.body))
+                executableLines++;
+            const operators = [], operands = [], sourceLineSet = new Set();
+            function tokens(current) {
+                if (current !== node && (isFunction(current) || ts.isTypeNode(current)))
+                    return;
+                // Markup contributes source lines, but not Halstead operators or operands.
+                if (ts.isJsxText(current))
+                    return;
+                const children = current.getChildren(source);
+                if (children.length) {
+                    children.forEach(tokens);
+                    return;
+                }
+                if (current.kind === ts.SyntaxKind.EndOfFileToken || current.getWidth(source) === 0)
+                    return;
+                const text = current.getText(source);
+                if (!["{", "}", ";"].includes(text))
+                    sourceLineSet.add(source.getLineAndCharacterOfPosition(current.getStart(source)).line);
+                if (ts.isIdentifier(current) || ts.isLiteralExpression(current))
+                    operands.push(text);
+                else
+                    operators.push(text);
+            }
+            tokens(node);
+            const vocabulary = new Set(operators).size + new Set(operands).size;
+            const volume = vocabulary > 1 ? (operators.length + operands.length) * Math.log2(vocabulary) : 0;
+            let inheritance = 0;
+            if (parentClass) {
+                const seen = new Set();
+                let current = checker.getTypeAtLocation(parentClass);
+                while (current && !seen.has(current)) {
+                    seen.add(current);
+                    current = current.getBaseTypes()?.[0];
+                    if (current)
+                        inheritance++;
+                }
+            }
+            const kind = parentClass ? "method" : /^use[A-Z]/.test(name) ? "hook" : hasJsx && /^[A-Z]/.test(name) ? "component" : "function";
+            const type = parentClass?.name?.text ?? (parentName || name);
+            const metric = { project, file, type, member, kind, line: source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1,
+                complexity, sourceLines: Math.max(1, sourceLineSet.size), executableLines, halsteadVolume: volume,
+                maintainabilityIndex: maintainability(volume, complexity, Math.max(1, sourceLineSet.size)), coupling: importCount, inheritance };
+            metrics.push(metric);
+            if (complexity > 10)
+                emit("highFunctionComplexity", "codeQuality", node, member, `${member} has cyclomatic complexity ${complexity} (threshold: 10).`, { measured: complexity, threshold: 10, metric: "cyclomaticComplexity", kind });
+            ts.forEachChild(node, child => visit(child, member));
+            return;
+        }
+        if (!ts.isTypeNode(node))
+            ts.forEachChild(node, child => visit(child, parentName));
+    }
+    visit(source);
+    const reactSupported = source.statements.some(statement => ts.isImportDeclaration(statement) && !statement.importClause?.isTypeOnly &&
+        ts.isStringLiteral(statement.moduleSpecifier) && statement.moduleSpecifier.text === "react");
+    return { metrics, findings, reactSupported };
+}

package/dist/scorecard-contract.d.ts

@@ -0,0 +1,6 @@
+export declare const ecosystemId = "javascript-typescript";
+export declare const defaultMetricsPath = ".scorecard/javascript-typescript/metrics.csv";
+export declare const defaultEvidencePath = ".scorecard/javascript-typescript/evidence.json";
+export declare const dimensionKeys: readonly ["codeQuality", "maintainability", "errorHandling", "performanceAsync", "security", "testing", "documentation", "dependencyManagement", "architecture"];
+export type DimensionKey = (typeof dimensionKeys)[number];
+export declare const metricsCsvHeader = "Scope,Project,Namespace,Type,Member,Maintainability Index,Cyclomatic Complexity,Depth of Inheritance,Class Coupling,Lines of Source code,Lines of Executable code";

package/dist/scorecard-contract.js

@@ -0,0 +1,15 @@
+export const ecosystemId = "javascript-typescript";
+export const defaultMetricsPath = ".scorecard/javascript-typescript/metrics.csv";
+export const defaultEvidencePath = ".scorecard/javascript-typescript/evidence.json";
+export const dimensionKeys = [
+    "codeQuality",
+    "maintainability",
+    "errorHandling",
+    "performanceAsync",
+    "security",
+    "testing",
+    "documentation",
+    "dependencyManagement",
+    "architecture",
+];
+export const metricsCsvHeader = "Scope,Project,Namespace,Type,Member,Maintainability Index,Cyclomatic Complexity,Depth of Inheritance,Class Coupling,Lines of Source code,Lines of Executable code";