vibecodedshit 0.0.0-stage → 0.2.0

package/methodology/v1.0/presets/generic.yaml

@@ -0,0 +1,41 @@
+preset:
+  key: generic
+  name: Generic
+  languages: [typescript, javascript, python]
+  detect: Used when no other preset matches.
+
+conventions: >-
+  Globs are relative to the package root and match with or without a src/
+  prefix (TypeScript, JavaScript) or a top-level package directory (Python).
+  When a file matches several layer globs, the innermost matching directory
+  decides its layer.
+
+layers:
+  shared: ["shared/**", "common/**", "lib/**", "utils/**", "helpers/**"]
+  features:
+    - "features/**"
+    - "modules/**"
+    - "routes/**"
+    - "pages/**"
+    - "app/**"
+    - "components/**"
+    - "views/**"
+    - "controllers/**"
+    - "api/**"
+
+modules:
+  roots: ["features/*", "modules/*", "packages/*"]
+  public_entry:
+    typescript_javascript: "index.{ts,tsx,js,jsx,mts,mjs,cjs}"
+    python: __init__.py
+
+rules:
+  - name: shared-does-not-import-features
+    description: Shared code does not depend on feature, route or UI code.
+    from: { in: [shared] }
+    to: { in: [features] }
+    severity: error
+    type_only_imports: included
+
+sources:
+  - "Martin, R. C. Clean Architecture. Prentice Hall, 2017 (the Dependency Rule)."

package/methodology/v1.0/presets/nextjs.yaml

@@ -0,0 +1,50 @@
+preset:
+  key: nextjs
+  name: Next.js
+  languages: [typescript, javascript]
+  detect: The package declares next as a dependency.
+
+conventions: >-
+  Globs are relative to the package root and match with or without a src/
+  prefix. When a file matches several layer globs, the innermost matching
+  directory decides its layer.
+
+layers:
+  routes: ["app/**", "pages/**"]
+  components: ["components/**"]
+  lib: ["lib/**", "utils/**"]
+  server_only: >-
+    Files that import the server-only package, files whose name contains
+    .server., and files under server/**.
+  client: Files whose first statement is the "use client" directive.
+
+modules:
+  roots: ["features/*", "modules/*", "packages/*"]
+  public_entry: "index.{ts,tsx,js,jsx,mts,mjs}"
+
+rules:
+  - name: routes-are-leaves
+    description: Nothing outside the route directories imports from them.
+    from: { not_in: [routes] }
+    to: { in: [routes] }
+    severity: error
+    type_only_imports: included
+  - name: lib-does-not-import-ui
+    description: Shared code does not depend on components or routes.
+    from: { in: [lib] }
+    to: { in: [components, routes] }
+    severity: error
+    type_only_imports: included
+  - name: client-does-not-import-server
+    description: >-
+      A client component does not directly import a server-only file or a
+      database package.
+    from: { in: [client] }
+    to:
+      in: [server_only]
+      packages: ["@prisma/client", drizzle-orm, pg, mysql2, mongoose, redis, ioredis, server-only]
+    severity: error
+    type_only_imports: excluded
+
+sources:
+  - "Next.js: Server and Client Components, keeping server-only code out of the client environment. https://nextjs.org/docs/app/getting-started/server-and-client-components"

package/methodology/v1.0/scope.yaml

@@ -0,0 +1,115 @@
+# Which files count, and how lines are counted.
+
+source_files:
+  start_from: git ls-files
+  extensions:
+    typescript: [.ts, .tsx, .mts, .cts]
+    javascript: [.js, .jsx, .mjs, .cjs]
+    python: [.py]
+
+exclusions:
+  # Fixed by the methodology. Applied before anything else.
+  vendored:
+    - "**/node_modules/**"
+    - "**/.venv/**"
+    - "**/venv/**"
+    - "**/vendor/**"
+    - "**/third_party/**"
+  build_output:
+    - "**/dist/**"
+    - "**/build/**"
+    - "**/.next/**"
+    - "**/out/**"
+    - "**/__pycache__/**"
+    - "**/coverage/**"
+  generated:
+    - files whose first 5 lines contain "@generated" or "Code generated"
+    - "**/*_pb2.py"
+    - "**/*_pb2_grpc.py"
+    - "**/node_modules/.prisma/**"
+    - "**/prisma/generated/**"
+    - "**/generated/prisma/**"
+  minified:
+    - "**/*.min.js"
+    - files whose average line length is over 300 characters
+  migrations:
+    - "**/prisma/migrations/**"
+    - "**/alembic/versions/**"
+    - "**/migrations/*.py"
+    - "**/drizzle/**/*.sql"
+  declarations:
+    - "**/*.d.ts"
+  test_data:
+    - "**/__fixtures__/**"
+    - "**/__snapshots__/**"
+    - "**/testdata/**"
+    - "**/test-data/**"
+    - "**/test/**/fixtures/**"
+    - "**/tests/**/fixtures/**"
+    - "**/__tests__/**/fixtures/**"
+    - "**/e2e/**/fixtures/**"
+
+file_roles:
+  test:
+    typescript_javascript:
+      - "**/*.test.{ts,tsx,mts,cts,js,jsx,mjs,cjs}"
+      - "**/*.spec.{ts,tsx,mts,cts,js,jsx,mjs,cjs}"
+      - "**/__tests__/**"
+      - "**/__mocks__/**"
+      - "**/test/**"
+      - "**/tests/**"
+      - "**/e2e/**"
+    python:
+      - "**/test_*.py"
+      - "**/*_test.py"
+      - "**/test/**"
+      - "**/tests/**"
+      - "**/conftest.py"
+  config:
+    - "**/*.config.{ts,mts,cts,js,mjs,cjs}"
+    - "**/*.config.*.{ts,mts,cts,js,mjs,cjs}"
+    - "**/.eslintrc.{js,cjs}"
+    - "**/setup.py"
+    - "**/noxfile.py"
+  logic: >-
+    An in-scope source file that is neither a test file nor a config file and
+    defines at least one function, method or class. Files that only re-export
+    (barrels), only declare types, or only declare constants are not logic
+    files.
+
+how_tests_are_used:
+  dimension_1: Test files are the subject of dimension 1.
+  typecheck_and_lint: >-
+    Test files are included in 2.1 (typecheck errors) and 2.5 (baseline lint
+    findings), because broken tests are a real problem.
+  other_static_metrics: >-
+    Test files are excluded from every other static metric in dimensions 2
+    to 4: escape hatches, typed surface, boundaries, cycles, complexity, file
+    size, duplication and dead code.
+
+line_counts:
+  logic_lines: >-
+    Non-blank lines that are not comment-only, in logic files. Python
+    docstrings count as comments. Used by 2.3, 4.2 and for unit_weighted
+    pooling.
+  source_lines: >-
+    Non-blank lines that are not comment-only, in logic files and test files.
+    Used by 2.1 and 2.5.
+
+healthignore:
+  file: .healthignore
+  syntax: gitignore patterns, relative to the repository root
+  allowed: true
+  safeguards:
+    - The report shows the percentage of lines excluded by .healthignore.
+    - health diff refuses to compare runs whose .healthignore contents differ.
+  does_not_apply_to: >-
+    The secret scan (5.4). Secret scanning covers every tracked file and only
+    honours .gitleaksignore, which is part of the ignore set.
+
+workspaces:
+  detection:
+    typescript_javascript: package.json "workspaces", pnpm-workspace.yaml
+    python: uv workspace members in pyproject.toml, or each directory with its own pyproject.toml
+  scoring: >-
+    One headline score for the repository. See pooling in methodology.yaml.

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "vibecodedshit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Codebase Health benchmark CLI",
+  "license": "Elastic-2.0",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "vibecodedshit": "dist/bin.js"
+  },
+  "files": [
+    "dist",
+    "methodology",
+    "python",
+    "assets",
+    "docker",
+    "LICENSE",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "coverage": "vitest run --coverage --coverage.provider=v8 --coverage.reporter=json-summary --coverage.reporter=text-summary --coverage.include=src/**",
+    "test:tools": "HEALTH_TOOLS=1 vitest run test/tools",
+    "test:docker": "HEALTH_DOCKER=1 vitest run test/docker",
+    "image:build": "docker build -t health:1.0 -f docker/Dockerfile docker",
+    "verify": "npm run typecheck && npm run lint && npm run test",
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build && npm run verify",
+    "health": "tsx src/bin.ts"
+  },
+  "dependencies": {
+    "@resvg/resvg-wasm": "2.6.2",
+    "@typescript-eslint/parser": "8.71.0",
+    "dependency-cruiser": "18.5.0",
+    "eslint": "9.39.5",
+    "eslint-plugin-sonarjs": "4.2.2",
+    "ignore": "^7.0.12",
+    "jscpd": "5.4.0",
+    "knip": "6.39.0",
+    "picomatch": "^4.0.7",
+    "semver": "7.8.5",
+    "smol-toml": "1.9.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "8.71.0",
+    "yaml": "^2.9.1",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.4",
+    "@types/picomatch": "^4.0.3",
+    "@types/semver": "^7.8.0",
+    "@vitest/coverage-v8": "^4.1.11",
+    "tsx": "^4.23.15",
+    "vitest": "^4.1.11"
+  }
+}

package/python/dead_code_helper.py

@@ -0,0 +1,265 @@
+"""Symbols, __all__, imports and class bases of Python files for the 4.4 dead-code parameter. Standard library only.
+
+Reads {"files": [relative paths]} as JSON on stdin and prints, per path,
+{"ok": bool,
+ "symbols": [{"name", "qualname", "kind": "function"|"class"|"method", "line", "startLine", "decorated"}],
+ "allNames": [str] | null,
+ "imports": [{"module": str, "level": int, "names": [str]}],
+ "classes": {class name: {"bases": [{"name": str, "file": str | null, "class": str | null}]}}}
+as JSON on stdout. "line" is the def/class line, "startLine" the first decorator line (or "line").
+A base with "file" and "class" resolves to a class defined in one of the scanned files; a base with
+null "file" is defined outside them (standard library, third party, or not resolvable). `object` and
+`Generic[...]` are left out. A file that cannot be read or parsed gives {"ok": false}.
+"""
+
+import ast
+import json
+import sys
+
+FUNCTIONS = (ast.FunctionDef, ast.AsyncFunctionDef)
+BLOCKS = (ast.If, ast.Try, ast.With, ast.AsyncWith)
+
+
+def start_line(node):
+    lines = [node.lineno] + [d.lineno for d in node.decorator_list]
+    return min(lines)
+
+
+def symbol(node, kind, qualname):
+    return {
+        "name": node.name,
+        "qualname": qualname,
+        "kind": kind,
+        "line": node.lineno,
+        "startLine": start_line(node),
+        "decorated": bool(node.decorator_list),
+    }
+
+
+def child_bodies(node):
+    if isinstance(node, ast.If):
+        return [node.body, node.orelse]
+    if isinstance(node, ast.Try):
+        bodies = [node.body, node.orelse, node.finalbody]
+        bodies.extend(handler.body for handler in node.handlers)
+        return bodies
+    return [node.body]
+
+
+def collect(statements, out):
+    """Module-level functions and classes, also inside top-level if/try/with, plus methods of those classes."""
+    for node in statements:
+        if isinstance(node, FUNCTIONS):
+            out.append(symbol(node, "function", node.name))
+        elif isinstance(node, ast.ClassDef):
+            out.append(symbol(node, "class", node.name))
+            for member in node.body:
+                if isinstance(member, FUNCTIONS):
+                    out.append(symbol(member, "method", node.name + "." + member.name))
+        elif isinstance(node, BLOCKS):
+            for body in child_bodies(node):
+                collect(body, out)
+
+
+def string_items(value):
+    if isinstance(value, (ast.List, ast.Tuple)):
+        return [e.value for e in value.elts if isinstance(e, ast.Constant) and isinstance(e.value, str)]
+    return None
+
+
+def all_names(tree):
+    names = None
+    for node in tree.body:
+        targets = []
+        value = None
+        if isinstance(node, ast.Assign):
+            targets, value = node.targets, node.value
+        elif isinstance(node, ast.AnnAssign) and node.value is not None:
+            targets, value = [node.target], node.value
+        elif isinstance(node, ast.AugAssign):
+            targets, value = [node.target], node.value
+        if not any(isinstance(t, ast.Name) and t.id == "__all__" for t in targets):
+            continue
+        items = string_items(value)
+        if items is not None:
+            names = (names or []) + items
+    return names
+
+
+def imports(tree):
+    found = []
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                found.append({"module": alias.name, "level": 0, "names": []})
+        elif isinstance(node, ast.ImportFrom):
+            found.append(
+                {
+                    "module": node.module or "",
+                    "level": node.level,
+                    "names": [alias.name for alias in node.names],
+                }
+            )
+    return found
+
+
+# ---- class bases ------------------------------------------------------------------------
+
+IGNORED_BASES = {"object", "Generic"}
+MAX_HOPS = 5
+
+
+def class_nodes(statements, out):
+    """Module-level classes, also inside top-level if/try/with (the same ones `collect` reports)."""
+    for node in statements:
+        if isinstance(node, ast.ClassDef):
+            out.append(node)
+        elif isinstance(node, BLOCKS):
+            for body in child_bodies(node):
+                class_nodes(body, out)
+
+
+def dotted(node):
+    """`a.b.C` as ["a", "b", "C"]; `Generic[T]` as its value; None for anything else (a call, ...)."""
+    if isinstance(node, ast.Subscript):
+        return dotted(node.value)
+    if isinstance(node, ast.Name):
+        return [node.id]
+    if isinstance(node, ast.Attribute):
+        head = dotted(node.value)
+        return None if head is None else head + [node.attr]
+    return None
+
+
+def bindings(tree):
+    """Module-level names bound by imports: name -> ("module", level, parts) or ("from", level, parts, name)."""
+    bound = {}
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                parts = alias.name.split(".")
+                if alias.asname:
+                    bound[alias.asname] = ("module", 0, parts)
+                else:
+                    bound[parts[0]] = ("module", 0, parts[:1])
+        elif isinstance(node, ast.ImportFrom):
+            parts = node.module.split(".") if node.module else []
+            for alias in node.names:
+                if alias.name != "*":
+                    bound[alias.asname or alias.name] = ("from", node.level, parts, alias.name)
+    return bound
+
+
+class Index:
+    """Classes and import bindings of every scanned file, and module lookup by path."""
+
+    def __init__(self, trees):
+        self.trees = trees
+        self.classes = {}
+        self.bound = {}
+        for path, tree in trees.items():
+            nodes = []
+            class_nodes(tree.body, nodes)
+            self.classes[path] = {node.name: node for node in nodes}
+            self.bound[path] = bindings(tree)
+
+    def module_file(self, importer, level, parts):
+        """The scanned file of a module, absolute (path suffix) or relative to `importer`."""
+        if level > 0:
+            base = importer.split("/")[:-1]
+            if level - 1 > len(base):
+                return None
+            base = base[: len(base) - (level - 1)]
+            stem = "/".join(base + parts)
+            for candidate in (stem + ".py", stem + "/__init__.py"):
+                if candidate in self.trees:
+                    return candidate
+            return None
+        if not parts:
+            return None
+        stem = "/".join(parts)
+        for candidate in sorted(self.trees):
+            for suffix in (stem + ".py", stem + "/__init__.py"):
+                if candidate == suffix or candidate.endswith("/" + suffix):
+                    return candidate
+        return None
+
+    def class_in(self, path, name, hops):
+        """(file, class) for `name` as seen from module `path`, following re-exports."""
+        if path is None or hops > MAX_HOPS:
+            return None
+        if name in self.classes.get(path, {}):
+            return (path, name)
+        binding = self.bound.get(path, {}).get(name)
+        if binding is None or binding[0] != "from":
+            return None
+        _, level, parts, imported = binding
+        return self.class_in(self.module_file(path, level, parts), imported, hops + 1)
+
+    def resolve(self, path, parts):
+        """Resolve base `parts` in module `path` to (file, class), or None."""
+        head, rest = parts[0], parts[1:]
+        if not rest and head in self.classes.get(path, {}):
+            return (path, head)
+        binding = self.bound.get(path, {}).get(head)
+        if binding is None:
+            return None
+        if binding[0] == "module":
+            _, level, mod = binding
+            module_parts = mod + rest[:-1]
+            if not rest:
+                return None
+            return self.class_in(self.module_file(path, level, module_parts), rest[-1], 0)
+        _, level, mod, imported = binding
+        if not rest:
+            return self.class_in(self.module_file(path, level, mod), imported, 0)
+        # `from pkg import module` then `module.Class`.
+        module = self.module_file(path, level, mod + [imported] + rest[:-1])
+        return self.class_in(module, rest[-1], 0)
+
+    def bases(self, path):
+        out = {}
+        for name, node in self.classes[path].items():
+            entries = []
+            for base in node.bases:
+                parts = dotted(base)
+                if parts is not None and parts[-1] in IGNORED_BASES:
+                    continue
+                found = self.resolve(path, parts) if parts is not None else None
+                text = ".".join(parts) if parts is not None else ast.dump(base)[:80]
+                entries.append({"name": text, "file": found[0] if found else None, "class": found[1] if found else None})
+            out[name] = {"bases": entries}
+        return out
+
+
+def parse(path):
+    try:
+        with open(path, "rb") as handle:
+            return ast.parse(handle.read(), filename=path)
+    except (OSError, SyntaxError, ValueError, RecursionError):
+        return None
+
+
+def analyze(path, tree, index):
+    if tree is None:
+        return {"ok": False}
+    symbols = []
+    collect(tree.body, symbols)
+    return {
+        "ok": True,
+        "symbols": symbols,
+        "allNames": all_names(tree),
+        "imports": imports(tree),
+        "classes": index.bases(path),
+    }
+
+
+def main():
+    request = json.load(sys.stdin)
+    trees = {path: parse(path) for path in request["files"]}
+    index = Index({path: tree for path, tree in trees.items() if tree is not None})
+    json.dump({path: analyze(path, tree, index) for path, tree in trees.items()}, sys.stdout)
+
+
+if __name__ == "__main__":
+    main()

package/python/env_helper.py

@@ -0,0 +1,71 @@
+"""Environment variable names read by Python files (6.5). Standard library only.
+
+Reads {"files": [relative paths]} as JSON on stdin and prints {path: {"ok": false} | {"ok": true, "names": [str]}}.
+Reads: os.environ["X"] (Load context only), os.environ.get("X"), os.getenv("X"), also through
+"from os import environ, getenv" and "import os as <alias>". Only literal string names count.
+"""
+
+import ast
+import json
+import sys
+
+
+def literal(node):
+    if isinstance(node, ast.Constant) and isinstance(node.value, str):
+        return node.value
+    return None
+
+
+def analyze(path):
+    with open(path, "rb") as handle:
+        tree = ast.parse(handle.read().decode("utf-8", errors="replace"), filename=path)
+    os_names, environ_names, getenv_names = set(), set(), set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                if alias.name == "os":
+                    os_names.add(alias.asname or "os")
+        elif isinstance(node, ast.ImportFrom) and node.level == 0 and node.module == "os":
+            for alias in node.names:
+                if alias.name == "environ":
+                    environ_names.add(alias.asname or "environ")
+                elif alias.name == "getenv":
+                    getenv_names.add(alias.asname or "getenv")
+
+    def is_environ(node):
+        if isinstance(node, ast.Name):
+            return node.id in environ_names
+        return isinstance(node, ast.Attribute) and node.attr == "environ" and isinstance(node.value, ast.Name) and node.value.id in os_names
+
+    names = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Subscript) and isinstance(node.ctx, ast.Load) and is_environ(node.value):
+            name = literal(node.slice)
+            if name is not None:
+                names.add(name)
+        elif isinstance(node, ast.Call) and node.args:
+            func = node.func
+            name = literal(node.args[0])
+            if name is None:
+                continue
+            if isinstance(func, ast.Attribute) and func.attr == "get" and is_environ(func.value):
+                names.add(name)
+            elif isinstance(func, ast.Attribute) and func.attr == "getenv" and isinstance(func.value, ast.Name) and func.value.id in os_names:
+                names.add(name)
+            elif isinstance(func, ast.Name) and func.id in getenv_names:
+                names.add(name)
+    return sorted(names)
+
+
+def main():
+    request = json.load(sys.stdin)
+    out = {}
+    for path in request["files"]:
+        try:
+            out[path] = {"ok": True, "names": analyze(path)}
+        except (SyntaxError, ValueError, OSError, RecursionError):
+            out[path] = {"ok": False}
+    json.dump(out, sys.stdout)
+
+
+main()