vibecodedshit 0.0.0-stage → 0.3.0

package/methodology/v1.0/dimensions/3-architecture-boundaries.yaml

@@ -0,0 +1,266 @@
+dimension:
+  id: 3
+  key: architecture_boundaries
+  name: Architecture & boundaries
+  question: Can you change one part without reading the rest?
+  agent_relevance: >-
+    An agent works inside a limited context window. Enforced boundaries
+    limit how much of the codebase one change can affect, so the agent only
+    needs to read the module it is changing and that module's public entry
+    points.
+
+presets:
+  description: >-
+    When a repository declares no import rules, the scan uses the preset for
+    the detected framework (presets/*.yaml). When it declares rules (see
+    3.1), its rules replace the preset. Detection order: nextjs, express,
+    django, fastapi, generic. Each workspace package gets its own preset.
+  files:
+    - presets/nextjs.yaml
+    - presets/express.yaml
+    - presets/django.yaml
+    - presets/fastapi.yaml
+    - presets/generic.yaml
+
+parameters:
+  - id: "3.1"
+    key: boundaries_declared
+    name: Boundaries declared and enforced
+    layer: static
+    weight: 15
+    requires: []
+    pooling: unit_weighted
+    raw:
+      unit: level
+      definition: >-
+        Whether the repository declares import rules in a supported rules
+        file, and whether CI runs them.
+      when_empty: 0
+    scoring:
+      method: levels
+      levels:
+        - level: none
+          score: 0
+          descriptor: No import rules are declared.
+        - level: declared
+          score: 50
+          descriptor: >-
+            A rules file declares at least one direction rule, but CI does
+            not run it.
+        - level: enforced
+          score: 100
+          descriptor: The rules are declared and CI runs them on pull requests.
+    measure:
+      typescript_javascript: >-
+        Rules file: .dependency-cruiser.{js,cjs,mjs,json}. Declared means at
+        least one forbidden or allowed rule whose from and to paths name
+        different directories. Enforced means a CI file invokes depcruise,
+        directly or through a package script or make target (up to 3 levels).
+      python: >-
+        Rules file: .importlinter, [importlinter] in setup.cfg, or
+        [tool.importlinter] in pyproject.toml. Declared means at least one
+        layers, forbidden or independence contract. Enforced means a CI file
+        invokes lint-imports, directly or through a script or make target.
+      ci_files: >-
+        .github/workflows/*, .gitlab-ci.yml, .circleci/config.yml,
+        bitbucket-pipelines.yml, azure-pipelines.yml.
+    not_applicable_when: null
+    rationale: >-
+      An architecture that exists only in people's heads is not visible to
+      an agent and erodes with each change. A rules file states the
+      architecture in a form a tool can check. Running it in CI is what stops
+      new violations.
+    sources:
+      - "dependency-cruiser rules reference. https://github.com/sverweij/dependency-cruiser/blob/main/doc/rules-reference.md"
+      - "import-linter contract types. https://import-linter.readthedocs.io/en/stable/contract_types.html"
+
+  - id: "3.2"
+    key: boundary_violations
+    name: Boundary violations
+    layer: static
+    weight: 30
+    requires: []
+    pooling: ratio
+    raw:
+      unit: violations per 1,000 imports
+      definition: >-
+        Import edges that break a rule, divided by all internal import edges
+        / 1,000. Rules come from the repository's declared rules file, or
+        from the preset when none is declared. Rules with severity error or
+        warn count; info is ignored. Each violating edge counts once, even
+        when it breaks several rules. Imports from test files are excluded.
+        Type-only imports are included, except where a preset rule says
+        otherwise.
+      when_empty: 100
+    scoring:
+      method: piecewise_linear
+      anchors:
+        - raw: 0
+          score: 100
+          descriptor: Every import respects the architecture.
+        - raw: 2
+          score: 75
+          descriptor: A few known shortcuts.
+        - raw: 10
+          score: 50
+          descriptor: The layers exist in name only in places.
+        - raw: 30
+          score: 0
+          descriptor: Anything imports anything.
+    measure:
+      typescript_javascript: dependency-cruiser with the declared rules or the preset converted to dependency-cruiser rules.
+      python: grimp builds the import graph; import-linter checks the declared contracts or the preset converted to contracts.
+    not_applicable_when: null
+    rationale: >-
+      Each violation is a dependency a reader would not expect from the
+      directory structure. The count is normalized per 1,000 imports so
+      repositories of different sizes are comparable.
+    sources:
+      - "Martin, R. C. Clean Architecture. Prentice Hall, 2017 (the Dependency Rule)."
+      - "Cockburn, A. Hexagonal Architecture (Ports and Adapters), 2005. https://alistair.cockburn.us/hexagonal-architecture/"
+
+  - id: "3.3"
+    key: import_cycles
+    name: Import cycles
+    layer: static
+    weight: 25
+    requires: []
+    pooling: ratio
+    raw:
+      unit: percent
+      definition: >-
+        Logic files that belong to an import cycle / all logic files. A cycle
+        is a strongly connected component of two or more files in the graph
+        of module-level static imports. Type-only imports, dynamic imports,
+        imports inside functions and imports under
+        "if TYPE_CHECKING:" are excluded.
+      when_empty: 100
+    scoring:
+      method: piecewise_linear
+      anchors:
+        - raw: 0
+          score: 100
+          descriptor: The import graph has no cycles.
+        - raw: 2
+          score: 75
+          descriptor: One or two small cycles.
+        - raw: 5
+          score: 50
+          descriptor: Cycles connect several areas.
+        - raw: 15
+          score: 0
+          descriptor: Large parts of the code depend on each other.
+    measure:
+      typescript_javascript: dependency-cruiser cycle detection on the filtered graph.
+      python: grimp import graph, filtered as defined, then strongly connected components.
+    not_applicable_when: null
+    rationale: >-
+      Files in a cycle cannot be understood, tested or changed one at a time.
+      Cycles also cause import-order bugs at runtime, especially in Python.
+      Type-only imports are excluded because they have no runtime effect.
+    sources:
+      - "Martin, R. C. Agile Software Development: Principles, Patterns, and Practices. Prentice Hall, 2002 (the Acyclic Dependencies Principle)."
+
+  - id: "3.4"
+    key: public_entry_discipline
+    name: Public-entry discipline
+    layer: static
+    weight: 15
+    requires: []
+    pooling: ratio
+    raw:
+      unit: percent
+      definition: >-
+        Imports that cross from one module into another and land on that
+        module's public entry / all imports that cross between modules.
+        Modules are defined by the preset (or by the independence or layer
+        contracts in the declared rules). The public entry is index.* in
+        TypeScript and JavaScript, and __init__.py in Python.
+      when_empty: 100
+    scoring:
+      method: piecewise_linear
+      anchors:
+        - raw: 50
+          score: 0
+          descriptor: Other modules reach into internals as often as not.
+        - raw: 75
+          score: 50
+          descriptor: Entry points exist and are often bypassed.
+        - raw: 90
+          score: 75
+          descriptor: Entry points are mostly used.
+        - raw: 100
+          score: 100
+          descriptor: Every cross-module import goes through the entry point.
+    measure:
+      typescript_javascript: Import graph from dependency-cruiser; module roots from the preset.
+      python: >-
+        grimp import graph; module roots from the preset. In Django apps,
+        models, services and selectors are also public entries.
+    not_applicable_when: >-
+      The repository has fewer than two modules as defined by the preset or
+      the declared rules. Splitting code into modules is a design choice the
+      methodology does not score.
+    rationale: >-
+      A public entry point is a small interface the next person can read
+      instead of the whole module. When other modules import internals
+      directly, every internal file becomes part of the interface and cannot
+      be changed safely.
+    sources:
+      - "HackSoft Django Styleguide. https://github.com/HackSoftware/Django-Styleguide"
+
+  - id: "3.5"
+    key: domain_purity
+    name: Domain purity
+    layer: static
+    weight: 15
+    requires: []
+    pooling: ratio
+    raw:
+      unit: percent
+      definition: >-
+        Files in the domain layer that import a framework, database, network
+        or filesystem package, or an infrastructure directory / all files in
+        the domain layer.
+      when_empty: 100
+    scoring:
+      method: piecewise_linear
+      anchors:
+        - raw: 0
+          score: 100
+          descriptor: Domain logic is plain code that runs and tests without infrastructure.
+        - raw: 5
+          score: 75
+          descriptor: A few domain files touch infrastructure.
+        - raw: 15
+          score: 50
+          descriptor: Domain logic regularly reaches for the database or the network.
+        - raw: 40
+          score: 0
+          descriptor: The domain layer is a directory name.
+    measure:
+      domain_layer: >-
+        Files under a directory named domain, or files in a layer named
+        domain in the declared rules.
+      typescript_javascript: >-
+        Forbidden imports: next, react, react-dom, express, @prisma/client,
+        drizzle-orm, pg, mysql2, mongoose, redis, ioredis, axios, node-fetch,
+        fs, node:fs, http, node:http, https, node:https. A call to the global
+        fetch also counts.
+      python: >-
+        Forbidden imports: django, fastapi, flask, starlette, sqlalchemy,
+        requests, httpx, aiohttp, boto3, psycopg, psycopg2, redis, pymongo.
+        A call to the builtin open also counts.
+      infrastructure_directories: infrastructure, infra, db, adapters.
+    not_applicable_when: >-
+      The repository declares no domain layer. Choosing a layered or
+      domain-driven design is a design choice the methodology does not score.
+    rationale: >-
+      This is the deterministic part of domain-driven design alignment. Pure
+      domain code can be tested without a database or network and changed
+      without reading infrastructure code. The methodology does not judge
+      whether the domain model is good; it checks that the repository keeps
+      the boundary it declared.
+    sources:
+      - "Evans, E. Domain-Driven Design. Addison-Wesley, 2003."
+      - "Cockburn, A. Hexagonal Architecture (Ports and Adapters), 2005. https://alistair.cockburn.us/hexagonal-architecture/"

package/methodology/v1.0/dimensions/4-complexity-maintainability.yaml

@@ -0,0 +1,192 @@
+dimension:
+  id: 4
+  key: complexity_maintainability
+  name: Complexity & maintainability
+  question: How much does someone have to read to make one change correctly?
+  agent_relevance: >-
+    Every line an agent reads uses context. Long files, complex functions,
+    duplicated logic and dead code all increase how much it must read, and
+    duplicated logic is where an agent fixes one copy and misses the other.
+
+parameters:
+  - id: "4.1"
+    key: complex_functions
+    name: Complex functions
+    layer: static
+    weight: 30
+    requires: []
+    pooling: ratio
+    raw:
+      unit: percent
+      definition: >-
+        Functions with cognitive complexity strictly greater than 15 / all
+        functions in logic files, as enumerated by the tool.
+      when_empty: 100
+    scoring:
+      method: piecewise_linear
+      anchors:
+        - raw: 0
+          score: 100
+          descriptor: Every function can be read in one pass.
+        - raw: 3
+          score: 75
+          descriptor: A few hard functions.
+        - raw: 8
+          score: 50
+          descriptor: Hard functions in most areas.
+        - raw: 20
+          score: 0
+          descriptor: Logic is concentrated in functions nobody wants to touch.
+    measure:
+      typescript_javascript: eslint-plugin-sonarjs cognitive-complexity rule, threshold 15.
+      python: complexipy, threshold 15.
+    not_applicable_when: null
+    rationale: >-
+      Cognitive complexity counts nesting and breaks in linear flow, which
+      is closer to how hard a function is to read than cyclomatic
+      complexity. 15 is the default threshold in SonarQube, eslint-plugin-sonarjs
+      and complexipy. Counting the share of functions over the threshold,
+      instead of the mean, keeps many small functions from hiding a few
+      large ones.
+    sources:
+      - "Campbell, G. A. Cognitive Complexity: A new way of measuring understandability. SonarSource, 2018. https://www.sonarsource.com/docs/CognitiveComplexity.pdf"
+      - "SonarQube rule S3776 (Cognitive Complexity of functions should not be too high), default threshold 15."
+      - "McCabe, T. J. A Complexity Measure. IEEE Transactions on Software Engineering, 1976 (cyclomatic complexity, threshold 10)."
+
+  - id: "4.2"
+    key: large_files
+    name: Lines in large files
+    layer: static
+    weight: 20
+    requires: []
+    pooling: ratio
+    raw:
+      unit: percent
+      definition: >-
+        Logic lines in logic files with more than 500 logic lines / all logic
+        lines.
+      when_empty: 100
+    scoring:
+      method: piecewise_linear
+      anchors:
+        - raw: 0
+          score: 100
+          descriptor: Every file fits in one read.
+        - raw: 10
+          score: 75
+          descriptor: A few large files.
+        - raw: 25
+          score: 50
+          descriptor: A quarter of the code lives in large files.
+        - raw: 50
+          score: 0
+          descriptor: Most of the code lives in files too large to read whole.
+    measure:
+      typescript_javascript: Logic line count per file (scope.yaml).
+      python: Logic line count per file (scope.yaml); docstrings do not count.
+    not_applicable_when: null
+    rationale: >-
+      A large file has to be read in parts, so changes to it are made with
+      partial context. The threshold of 500 logic lines is more lenient than
+      ESLint's max-lines default (300 physical lines) and stricter than
+      Pylint's max-module-lines default (1,000). The raw value is a share of
+      lines, not of files, so one 5,000-line file weighs more than one
+      501-line file.
+    sources:
+      - "ESLint max-lines rule, default 300. https://eslint.org/docs/latest/rules/max-lines"
+      - "Pylint too-many-lines (C0302), max-module-lines default 1000."
+
+  - id: "4.3"
+    key: duplication
+    name: Duplication
+    layer: static
+    weight: 25
+    requires: []
+    pooling: ratio
+    raw:
+      unit: percent
+      definition: Duplicated lines / all lines in logic files, as reported by jscpd.
+      when_empty: 100
+    scoring:
+      method: piecewise_linear
+      anchors:
+        - raw: 3
+          score: 100
+          descriptor: Duplication is incidental.
+        - raw: 5
+          score: 75
+          descriptor: Some copied blocks.
+        - raw: 10
+          score: 50
+          descriptor: Copy and paste is a common way to add features.
+        - raw: 20
+          score: 0
+          descriptor: Large parts of the logic exist in several copies.
+    measure:
+      typescript_javascript: jscpd, min-tokens 50, min-lines 5, logic files only.
+      python: jscpd, same settings.
+    not_applicable_when: null
+    rationale: >-
+      A bug fixed in one copy stays in the others. This is a common agent
+      mistake: the agent finds one copy, fixes it, and its tests pass. 3% is
+      the default duplication limit in SonarQube's quality gate.
+    sources:
+      - "SonarQube default quality gate (Sonar way): duplicated lines on new code at most 3%."
+      - "jscpd. https://github.com/kucherenko/jscpd"
+
+  - id: "4.4"
+    key: dead_code
+    name: Unused exports and files
+    layer: static
+    weight: 25
+    requires: []
+    pooling: ratio
+    raw:
+      unit: percent
+      definition: >-
+        (Unused exported symbols + exported symbols in unused files) / all
+        exported symbols in logic files. Exported types count. Library entry
+        points (package.json exports and main, Python __all__ of a
+        distributed package) count as used.
+      when_empty: 100
+    scoring:
+      method: piecewise_linear
+      anchors:
+        - raw: 0
+          score: 100
+          descriptor: Everything exported is used.
+        - raw: 3
+          score: 75
+          descriptor: A little dead code.
+        - raw: 8
+          score: 50
+          descriptor: Dead code is common.
+        - raw: 20
+          score: 0
+          descriptor: A large share of the code is never called.
+    measure:
+      typescript_javascript: knip (unused files, exports and types), with framework plugins enabled.
+      python: >-
+        vulture with min-confidence 60 for unused functions, classes and
+        methods; decorated definitions are treated as used. A method is
+        also treated as used when its class, directly or through base
+        classes defined in the repository, has a base class defined
+        outside the repository (standard library or third party), or when
+        a base class defined in the repository has a method of the same
+        name; object and Generic do not count as bases. Unused modules:
+        modules no other module imports, excluding entry modules (__main__,
+        manage.py, wsgi, asgi, settings, conftest, targets of
+        [project.scripts], Django convention modules such as models, admin,
+        apps, urls, views, and FastAPI main.py).
+    not_applicable_when: null
+    rationale: >-
+      Dead code costs reading time and looks like a place to make a change.
+      An agent that edits an unused function gets no test failure and no
+      effect. Decorated Python definitions are treated as used because
+      frameworks register them by decorator (routes, fixtures, signals).
+      Methods that override a base class are treated as used for the same
+      reason: frameworks and the standard library call hooks such as
+      do_GET, setUp or emit by name, which vulture cannot see.
+    sources:
+      - "knip. https://knip.dev"
+      - "vulture. https://github.com/jendrikseipp/vulture"

package/methodology/v1.0/dimensions/5-dependency-security-hygiene.yaml

@@ -0,0 +1,223 @@
+dimension:
+  id: 5
+  key: dependency_security_hygiene
+  name: Dependency & security hygiene
+  question: Is the code built on parts that are known, current and safe?
+  agent_relevance: >-
+    An agent adds dependencies and copies patterns from what it finds. An
+    undeclared dependency, a stale major version or a committed secret gets
+    copied into new code the same way good patterns do.
+
+as_of_date: >-
+  Parameters 5.1 and 5.2 are evaluated at the run's as-of date: advisories
+  published on or before that date count, and the latest version of a
+  package is the latest published on or before that date.
+
+parameters:
+  - id: "5.1"
+    key: known_vulnerabilities
+    name: Known vulnerabilities in production dependencies
+    layer: static
+    weight: 30
+    requires: []
+    pooling: ratio
+    raw:
+      unit: severity points
+      definition: >-
+        Sum of severity points over advisories affecting resolved production
+        dependencies (direct and transitive). Critical 10, high 5, moderate 2,
+        low 0.5. Each advisory counts once per package; aliases are
+        deduplicated. Withdrawn advisories are excluded.
+      when_empty: 100
+    scoring:
+      method: piecewise_linear
+      anchors:
+        - raw: 0
+          score: 100
+          descriptor: No known vulnerabilities.
+        - raw: 2
+          score: 75
+          descriptor: One moderate, or a few low.
+        - raw: 10
+          score: 50
+          descriptor: A critical, or several highs.
+        - raw: 30
+          score: 0
+          descriptor: Several criticals. Nobody is watching.
+    measure:
+      typescript_javascript: osv-scanner on the lockfile, against the OSV snapshot for the as-of date. Production dependencies only.
+      python: osv-scanner on the lockfile, against the OSV snapshot for the as-of date. Production dependencies only.
+      severity: >-
+        The GitHub Security Advisory severity label when present. Otherwise
+        the CVSS v3.1 base score band (critical 9.0-10.0, high 7.0-8.9,
+        moderate 4.0-6.9, low 0.1-3.9). Otherwise moderate.
+    not_applicable_when: null
+    rationale: >-
+      Severity points stop one critical advisory from scoring the same as
+      one low one. The count is not normalized by repository size, because
+      a vulnerability's risk does not shrink as the codebase grows.
+      Development-only dependencies are reported separately and not scored.
+    sources:
+      - "OSV schema (published, withdrawn, aliases). https://ossf.github.io/osv-schema/"
+      - "FIRST. CVSS v3.1 Specification, qualitative severity rating scale. https://www.first.org/cvss/v3.1/specification-document"
+
+  - id: "5.2"
+    key: major_versions_behind
+    name: Dependencies a major version behind
+    layer: static
+    weight: 20
+    requires: []
+    pooling: ratio
+    raw:
+      unit: percent
+      definition: >-
+        Direct dependencies (production and development) whose resolved
+        version is at least one major version behind the highest stable,
+        non-yanked version published on or before the as-of date / all direct
+        dependencies. For 0.x versions, a minor version bump counts as major.
+      when_empty: 100
+    scoring:
+      method: piecewise_linear
+      anchors:
+        - raw: 0
+          score: 100
+          descriptor: Every direct dependency is on its current major.
+        - raw: 10
+          score: 75
+          descriptor: A few dependencies are behind.
+        - raw: 25
+          score: 50
+          descriptor: A quarter of dependencies are behind.
+        - raw: 50
+          score: 0
+          descriptor: Upgrades have stopped.
+    measure:
+      typescript_javascript: npm registry publish times from the registry snapshot.
+      python: PyPI release upload times from the registry snapshot.
+    not_applicable_when: null
+    rationale: >-
+      Each major version behind is a migration someone will have to do, and
+      an agent writing code against current documentation will use APIs the
+      installed version does not have. Development dependencies are included
+      because outdated tooling affects every change.
+    sources:
+      - "Semantic Versioning 2.0.0, item 4 (major version zero). https://semver.org"
+
+  - id: "5.3"
+    key: lockfile
+    name: Lockfile
+    layer: static
+    weight: 15
+    requires: []
+    pooling: unit_weighted
+    raw:
+      unit: level
+      definition: Whether a lockfile exists and matches the manifest.
+      when_empty: 0
+    scoring:
+      method: levels
+      levels:
+        - level: none
+          score: 0
+          descriptor: No lockfile. Every install can resolve different versions.
+        - level: out_of_sync
+          score: 40
+          descriptor: A lockfile exists but does not match the manifest.
+        - level: in_sync
+          score: 100
+          descriptor: The lockfile matches the manifest.
+    measure:
+      typescript_javascript: >-
+        package-lock.json, npm-shrinkwrap.json, pnpm-lock.yaml, yarn.lock or
+        bun.lock. In sync means every dependency declared in package.json is
+        present in the lockfile with a version that satisfies its range.
+      python: >-
+        uv.lock, poetry.lock, pdm.lock, Pipfile.lock, or requirements files
+        with every requirement pinned with == and --hash. In sync means
+        every dependency declared in pyproject.toml (or Pipfile) is in the
+        lockfile with a version that satisfies its specifier, or for
+        uv.lock and poetry.lock, the lockfile's recorded manifest hash
+        matches.
+    not_applicable_when: null
+    rationale: >-
+      Without a lockfile, two installs of the same commit can produce
+      different code. Results stop being reproducible, including this
+      methodology's results.
+    sources:
+      - "npm ci documentation. https://docs.npmjs.com/cli/commands/npm-ci"
+
+  - id: "5.4"
+    key: secrets_in_tree
+    name: Secrets in the working tree
+    layer: static
+    weight: 20
+    requires: []
+    pooling: unit_weighted
+    raw:
+      unit: count
+      definition: >-
+        Secrets found by the pinned gitleaks default ruleset in every
+        tracked file at the scanned commit. .healthignore does not apply.
+        .gitleaksignore applies and is part of the ignore set.
+      when_empty: 100
+    scoring:
+      method: piecewise_linear
+      anchors:
+        - raw: 0
+          score: 100
+          descriptor: No secrets in the code.
+        - raw: 1
+          score: 0
+          descriptor: At least one secret is in the code.
+    measure:
+      all_languages: gitleaks dir on the checkout, default ruleset of the pinned version.
+    not_applicable_when: null
+    rationale: >-
+      One committed secret is enough to cause a breach, so the parameter is
+      binary. Secrets in git history are reported but not scored, because
+      the fix is rotating the key, which cannot be seen in the code.
+    sources:
+      - "CWE-798: Use of Hard-coded Credentials. https://cwe.mitre.org/data/definitions/798.html"
+      - "gitleaks. https://github.com/gitleaks/gitleaks"
+
+  - id: "5.5"
+    key: declaration_errors
+    name: Dependency declaration errors
+    layer: static
+    weight: 15
+    requires: []
+    pooling: ratio
+    raw:
+      unit: percent
+      definition: >-
+        (Declared dependencies that are never imported + imported packages
+        that are not declared) / declared direct dependencies.
+      when_empty: 100
+    scoring:
+      method: piecewise_linear
+      anchors:
+        - raw: 0
+          score: 100
+          descriptor: The manifest matches the code.
+        - raw: 5
+          score: 75
+          descriptor: A few stale or missing entries.
+        - raw: 15
+          score: 50
+          descriptor: The manifest and the code have drifted apart.
+        - raw: 30
+          score: 0
+          descriptor: Nobody maintains the manifest.
+    measure:
+      typescript_javascript: knip unused dependencies plus unlisted dependencies.
+      python: >-
+        deptry DEP001 (missing), DEP002 (unused) and DEP003 (transitive
+        imported directly). DEP004 (development dependency used in
+        production code) is not counted.
+    not_applicable_when: null
+    rationale: >-
+      An undeclared import works until the transitive dependency that
+      provides it changes. An unused declaration adds install time and
+      attack surface. Both mislead a reader about what the code depends on.
+    sources:
+      - "deptry rules. https://deptry.com/rules-violations/"