edsger 0.77.0 → 0.78.0

package/assets/benchmark/typescript.yaml

@@ -0,0 +1,71 @@
+id: typescript
+name: TypeScript / JavaScript Overlay
+version: 0.1.0
+kind: benchmark
+extends: base
+appliesTo: [typescript]
+scoreScale: 4
+
+# Overlay categories are merged onto base. The `language` category is new;
+# criteria added to existing categories (by category id) extend them.
+categories:
+  - id: language
+    name: TypeScript / JS Language Quality
+    weight: 14
+    description: Idiomatic, type-safe, ecosystem-aligned JavaScript/TypeScript.
+    criteria:
+      - id: ts-strictness
+        title: TypeScript strict mode and no implicit any
+        guidance: >
+          Check tsconfig for `strict: true` (and ideally
+          `noUncheckedIndexedAccess`). Penalise pervasive `any`, `@ts-ignore`,
+          and `as any` casts that defeat the type system.
+        rubric:
+          excellent: strict + noUncheckedIndexedAccess; `any`/ts-ignore are rare and justified.
+          adequate: strict mode on but with scattered `any`/ts-ignore.
+          poor: strict off, or types routinely bypassed with `any`.
+        references:
+          - "https://www.typescriptlang.org/tsconfig#strict"
+      - id: lint-format-toolchain
+        title: ESLint + Prettier (or Biome) enforced
+        guidance: >
+          A linter and formatter should be configured and runnable, ideally in
+          CI and a pre-commit hook. Flat ESLint config or Biome are both fine.
+        rubric:
+          excellent: Lint + format configured and enforced in CI/hooks with no disabled core rules en masse.
+          adequate: Configured but not enforced.
+          poor: No linter/formatter.
+      - id: async-correctness
+        title: Correct async/Promise handling
+        guidance: >
+          Look for unhandled promise rejections, missing `await`, floating
+          promises, and `async` functions that swallow errors. Prefer
+          async/await over nested callbacks.
+        rubric:
+          excellent: No floating promises; errors propagated; no unbounded concurrency.
+          adequate: Mostly correct with a few floating promises.
+          poor: Pervasive unhandled rejections / missing awaits.
+      - id: package-hygiene
+        title: Healthy package.json and module setup
+        guidance: >
+          Check for a committed lockfile, pinned engines, correct `type`
+          (module/commonjs) and `exports`, separation of dependencies vs
+          devDependencies, and no unused or duplicated dependencies.
+        rubric:
+          excellent: Clean package.json; lockfile committed; engines + exports declared correctly.
+          adequate: Works but with dependency/exports rough edges.
+          poor: No lockfile or broken/duplicated dependency declarations.
+
+  # Extend base testing with the JS ecosystem expectation of typecheck-in-CI.
+  - id: testing
+    name: Testing & Verification
+    weight: 18
+    criteria:
+      - id: typecheck-in-ci
+        title: tsc --noEmit (type check) runs in CI
+        guidance: >
+          A passing type check should gate merges in addition to unit tests.
+        rubric:
+          excellent: "`tsc --noEmit` (or build) runs and is required in CI."
+          adequate: Type checking exists locally but not enforced.
+          poor: No type checking step.

package/assets/languages.yaml

@@ -0,0 +1,35 @@
+# Language detection heuristics used by edsger to pick which overlays to apply.
+#
+# Detection is evidence-based. For each language we score:
+#   - `markers`: presence of a manifest/config file (strong signal, weight 3)
+#   - `extensions`: source file extensions found in the repo (weight 1 each, capped)
+# A language is considered "present" when its score crosses `minScore`.
+# Multiple languages can be detected for polyglot repos; overlays stack.
+version: 1
+minScore: 3
+maxExtensionMatches: 5   # cap extension contribution so manifests dominate
+
+languages:
+  - id: typescript
+    markers: [package.json, tsconfig.json, deno.json, pnpm-lock.yaml, yarn.lock]
+    extensions: [.ts, .tsx, .js, .jsx, .mjs, .cjs]
+
+  - id: python
+    markers: [pyproject.toml, setup.py, setup.cfg, requirements.txt, Pipfile, poetry.lock]
+    extensions: [.py, .pyi]
+
+  - id: go
+    markers: [go.mod, go.sum]
+    extensions: [.go]
+
+  - id: csharp
+    markers: ["*.sln", "*.csproj", "global.json", Directory.Build.props]
+    extensions: [.cs, .csx]
+
+  - id: java
+    markers: [pom.xml, build.gradle, build.gradle.kts, settings.gradle, build.gradle.kts]
+    extensions: [.java, .kt, .kts]
+
+  - id: dart
+    markers: [pubspec.yaml, pubspec.lock]
+    extensions: [.dart]

package/assets/manifest.yaml

@@ -0,0 +1,39 @@
+# edsger-assets registry.
+# Consumed by the edsger CLI to discover available standards and defaults.
+schemaVersion: 1
+name: edsger-assets
+version: 0.1.0
+description: Industrial-grade benchmark rubrics and PR review standards.
+
+# Standard kinds shipped in this repository.
+kinds:
+  benchmark:
+    dir: benchmark
+    base: base
+    schema: schema/benchmark.schema.json
+  review:
+    dir: review
+    base: base
+    schema: schema/review.schema.json
+
+# Languages with dedicated overlays. `id` matches the detector in languages.yaml.
+# `aliases` are accepted on the CLI (e.g. `--lang ts`).
+languages:
+  - id: typescript
+    name: TypeScript / JavaScript
+    aliases: [ts, js, javascript, node, nodejs]
+  - id: python
+    name: Python
+    aliases: [py]
+  - id: go
+    name: Go
+    aliases: [golang]
+  - id: csharp
+    name: C# / .NET
+    aliases: [cs, dotnet, "c#"]
+  - id: java
+    name: Java
+    aliases: [jvm, kotlin]
+  - id: dart
+    name: Dart / Flutter
+    aliases: [flutter]

package/assets/review/base.yaml

@@ -0,0 +1,111 @@
+id: base
+name: Universal PR Review Standard
+version: 0.1.0
+kind: review
+extends: null
+appliesTo: ["*"]
+
+policy:
+  # Findings at these severities should request changes / block merge.
+  blockingSeverities: [critical, high]
+  commentStyle: both          # inline comments + a summary
+  maxComments: 25             # avoid burying the author
+  tone: >
+    Be specific, kind, and actionable. Critique the code, not the author.
+    Explain the "why" and suggest a concrete fix. Acknowledge good work.
+    Distinguish blocking issues from optional nitpicks (prefix nits with "nit:").
+
+focusAreas:
+  - id: correctness
+    title: Correctness & Logic
+    defaultSeverity: high
+    guidance: >
+      Does the change do what it claims? Look for off-by-one errors, wrong
+      conditionals, broken edge cases (empty/null, boundaries, large inputs),
+      incorrect error handling, race conditions, and regressions in existing
+      behaviour. Verify the diff actually implements the PR description.
+    checklist:
+      - Edge cases and empty/null inputs handled
+      - Error and failure paths are correct and tested
+      - No unintended behavioural change to existing callers
+      - Concurrency/ordering assumptions hold
+
+  - id: security
+    title: Security
+    defaultSeverity: critical
+    guidance: >
+      Treat all changed inputs as untrusted. Look for injection (SQL, command,
+      path, template), missing authn/authz checks, secrets added to code or
+      logs, unsafe deserialization, SSRF, and weakened crypto. New dependencies
+      should be reputable and pinned.
+    checklist:
+      - No secrets/keys added to code, config, or logs
+      - Untrusted input validated; queries parameterised; output encoded
+      - Authorization enforced on new privileged paths
+      - New dependencies are necessary, reputable, and pinned
+    references:
+      - "https://owasp.org/www-project-top-ten/"
+
+  - id: tests
+    title: Test Coverage
+    defaultSeverity: high
+    guidance: >
+      New logic and bug fixes should come with tests. A bug fix should include a
+      test that fails without the fix. Check that tests assert behaviour, are
+      deterministic, and cover the edge cases introduced by the change.
+    checklist:
+      - New/changed logic is covered by tests
+      - Bug fixes include a regression test
+      - Tests are deterministic and isolated
+
+  - id: design
+    title: Design & Maintainability
+    defaultSeverity: medium
+    guidance: >
+      Is this the right change at the right layer? Watch for unnecessary
+      complexity, duplication, leaky abstractions, public API changes without
+      need, and changes that will be hard to evolve. Prefer the simplest design
+      that solves the problem. Per Google's guidance, approve changes that
+      improve overall code health even if not perfect.
+    checklist:
+      - Change is at the appropriate layer with a clear responsibility
+      - No needless complexity or duplication introduced
+      - Public API / interface changes are justified and minimal
+    references:
+      - "https://google.github.io/eng-practices/review/reviewer/"
+
+  - id: readability
+    title: Readability & Naming
+    defaultSeverity: low
+    guidance: >
+      Names are clear, functions are reasonably small, control flow is easy to
+      follow, and comments explain non-obvious "why". Style nits handled by an
+      autoformatter should not dominate the review.
+    checklist:
+      - Names communicate intent
+      - Non-obvious decisions are commented
+      - Dead code / debug logging removed
+
+  - id: performance
+    title: Performance & Resources
+    defaultSeverity: medium
+    guidance: >
+      Look for accidental O(n^2) loops, N+1 queries, unbounded memory/concurrency,
+      blocking calls on hot paths, and leaked resources (files, connections,
+      goroutines/threads). Optimise only where it matters; flag obvious waste.
+    checklist:
+      - No N+1 queries or accidental quadratic loops on hot paths
+      - Resources (files, connections, handles) are released
+      - Concurrency is bounded
+
+  - id: docs-and-compat
+    title: Documentation & Compatibility
+    defaultSeverity: low
+    guidance: >
+      User-facing changes update docs/README/CHANGELOG. Breaking changes to
+      public APIs, CLIs, config, or data formats are called out and versioned.
+      Database/schema migrations are backward-compatible or sequenced safely.
+    checklist:
+      - Docs/README/CHANGELOG updated for user-facing changes
+      - Breaking changes flagged and versioned
+      - Migrations are safe and reversible where possible

package/assets/review/csharp.yaml

@@ -0,0 +1,38 @@
+id: csharp
+name: C# / .NET Review Overlay
+version: 0.1.0
+kind: review
+extends: base
+appliesTo: [csharp]
+
+focusAreas:
+  - id: cs-async
+    title: Async Correctness
+    defaultSeverity: high
+    guidance: >
+      Flag `async void` (outside event handlers), `.Result`/`.Wait()`/
+      `.GetAwaiter().GetResult()` on async code (deadlock/stall risk), and missing
+      CancellationToken propagation. Prefer `ConfigureAwait(false)` in libraries.
+    checklist:
+      - No blocking on async; no async void
+      - CancellationToken flowed through async APIs
+
+  - id: cs-nullsafety
+    title: Null-safety & Disposal
+    defaultSeverity: medium
+    guidance: >
+      With nullable reference types enabled, flag new `!` null-forgiving operators
+      and `#nullable disable`. Ensure IDisposable/IAsyncDisposable are disposed
+      (using/await using). Watch for returning null instead of empty collections.
+    checklist:
+      - Disposables released via using/await using
+      - No unjustified null-forgiving (!) operators
+
+  - id: cs-linq-perf
+    title: LINQ & Allocation
+    defaultSeverity: low
+    guidance: >
+      Watch for multiple enumeration of IEnumerable, LINQ in hot loops, and
+      EF Core N+1 / client-side evaluation. Materialise queries intentionally.
+    checklist:
+      - No accidental multiple enumeration or EF N+1

package/assets/review/dart.yaml

@@ -0,0 +1,40 @@
+id: dart
+name: Dart / Flutter Review Overlay
+version: 0.1.0
+kind: review
+extends: base
+appliesTo: [dart]
+
+focusAreas:
+  - id: dart-nullsafety
+    title: Null-safety & Analysis
+    defaultSeverity: medium
+    guidance: >
+      Flag new `!` null-assertions and `late` where a nullable type and explicit
+      handling would be safer. The change should not introduce `dart analyze`
+      warnings or ignore comments without justification.
+    checklist:
+      - Minimal, justified use of `!` and `late`
+      - No new analyzer warnings / unexplained `// ignore:`
+
+  - id: dart-async
+    title: Async & Streams
+    defaultSeverity: high
+    guidance: >
+      Ensure Futures are awaited, errors handled, and StreamSubscriptions /
+      controllers are cancelled/closed (often in dispose). Watch for unawaited
+      futures that drop errors.
+    checklist:
+      - Streams/subscriptions cancelled; controllers closed
+      - No silently unawaited futures
+
+  - id: flutter-widgets
+    title: Flutter Widget Hygiene
+    defaultSeverity: low
+    guidance: >
+      For Flutter changes: use `const` constructors where possible, avoid heavy
+      work in build(), dispose controllers/listeners, and avoid passing
+      BuildContext across async gaps. Skip for non-Flutter packages.
+    checklist:
+      - Controllers/animations disposed; no work in build()
+      - No BuildContext used across async gaps (mounted checked)

package/assets/review/go.yaml

@@ -0,0 +1,40 @@
+id: go
+name: Go Review Overlay
+version: 0.1.0
+kind: review
+extends: base
+appliesTo: [go]
+
+focusAreas:
+  - id: go-errors
+    title: Error Handling
+    defaultSeverity: high
+    guidance: >
+      Errors must be checked, not discarded with `_`. New error returns should be
+      wrapped with context (`%w`). Flag panics used for ordinary control flow and
+      lost error context.
+    checklist:
+      - All errors checked and wrapped with context
+      - No panic for recoverable conditions
+
+  - id: go-concurrency
+    title: Concurrency Safety
+    defaultSeverity: critical
+    guidance: >
+      Check goroutines for clear termination (context cancellation), data races
+      on shared state, and correct mutex/channel use. New concurrent code should
+      pass `go test -race`. Watch for goroutine leaks.
+    checklist:
+      - Goroutines have bounded lifetime (context) and cannot leak
+      - Shared state protected; no data races
+
+  - id: go-idiom
+    title: Idiom & Resources
+    defaultSeverity: medium
+    guidance: >
+      Use `defer` to release resources (files, locks, response bodies). Accept
+      interfaces, return structs. Avoid unnecessary allocations on hot paths and
+      unkeyed struct literals across package boundaries.
+    checklist:
+      - Resources closed via defer (incl. http.Response.Body)
+      - Context propagated through call chains

package/assets/review/java.yaml

@@ -0,0 +1,40 @@
+id: java
+name: Java / JVM Review Overlay
+version: 0.1.0
+kind: review
+extends: base
+appliesTo: [java]
+
+focusAreas:
+  - id: java-resources
+    title: Resources & Null-safety
+    defaultSeverity: high
+    guidance: >
+      Use try-with-resources for anything Closeable. Flag swallowed exceptions
+      (empty catch), returning null collections, and NPE-prone access. Prefer
+      Optional or nullability annotations to communicate intent.
+    checklist:
+      - try-with-resources for Closeable resources
+      - No empty catch blocks; nullability is explicit
+
+  - id: java-concurrency
+    title: Concurrency & Immutability
+    defaultSeverity: critical
+    guidance: >
+      Check shared mutable state for proper synchronization, prefer immutable
+      objects and concurrent collections, and avoid leaking `this` from
+      constructors. Validate thread-pool/executor lifecycle and shutdown.
+    checklist:
+      - Shared state is synchronized or immutable
+      - Executors are shut down; no thread leaks
+
+  - id: java-api
+    title: API & Dependency Hygiene
+    defaultSeverity: medium
+    guidance: >
+      Public API changes should preserve binary/source compatibility or be
+      versioned. New dependencies should be justified and version-managed via the
+      BOM/catalog. Watch for overly broad visibility (prefer package-private).
+    checklist:
+      - Public API changes are compatible or versioned
+      - New deps managed via BOM/version catalog

package/assets/review/python.yaml

@@ -0,0 +1,41 @@
+id: python
+name: Python Review Overlay
+version: 0.1.0
+kind: review
+extends: base
+appliesTo: [python]
+
+focusAreas:
+  - id: py-types-style
+    title: Typing & Pythonic Style
+    defaultSeverity: low
+    guidance: >
+      New/changed public functions should carry type hints. Prefer comprehensions
+      and context managers over manual loops/resource handling. Flag mutable
+      default arguments, bare `except:`, and broad `except Exception` that hides
+      errors.
+    checklist:
+      - Public functions typed; no mutable default args
+      - No bare/over-broad except swallowing errors
+      - Context managers used for files/locks/connections
+
+  - id: py-security
+    title: Python Security Pitfalls
+    defaultSeverity: critical
+    guidance: >
+      Flag `eval`/`exec`/`pickle` on untrusted data, `subprocess(..., shell=True)`
+      with interpolated input, `yaml.load` without SafeLoader, and SQL built via
+      f-strings. Prefer parameterised queries and `subprocess` arg lists.
+    checklist:
+      - No shell=True with untrusted input; no eval/exec/pickle on untrusted data
+      - SQL parameterised; YAML uses safe_load
+
+  - id: py-correctness
+    title: Runtime Correctness
+    defaultSeverity: high
+    guidance: >
+      Watch for late-binding closures in loops, integer/float surprises, and
+      blocking calls inside async code. Ensure asyncio tasks are awaited and
+      exceptions are not lost.
+    checklist:
+      - No un-awaited asyncio tasks / blocking calls in async paths

package/assets/review/typescript.yaml

@@ -0,0 +1,40 @@
+id: typescript
+name: TypeScript / JavaScript Review Overlay
+version: 0.1.0
+kind: review
+extends: base
+appliesTo: [typescript]
+
+focusAreas:
+  - id: ts-types
+    title: Type Safety
+    defaultSeverity: medium
+    guidance: >
+      Flag new `any`, `as any`, and `@ts-ignore`/`@ts-expect-error` without a
+      justifying comment. Prefer precise types, discriminated unions, and
+      `unknown` over `any` at boundaries. Watch for unsafe non-null assertions (!).
+    checklist:
+      - No new untyped `any` or unexplained ts-ignore
+      - External/boundary data validated (e.g. zod) before being trusted as typed
+
+  - id: ts-async
+    title: Async & Promise Safety
+    defaultSeverity: high
+    guidance: >
+      Catch floating promises (un-awaited async calls), missing error handling
+      on awaited calls, and unbounded `Promise.all` over large arrays. Ensure
+      cleanup (timers, listeners, abort controllers) on all paths.
+    checklist:
+      - No floating promises; rejections handled
+      - Event listeners/timers cleaned up
+
+  - id: ts-runtime
+    title: Runtime & Ecosystem
+    defaultSeverity: medium
+    guidance: >
+      Check for accidental Node/browser API misuse, CommonJS/ESM mismatch,
+      mutation of shared/exported objects, and use of deprecated APIs. New deps
+      should be justified (bundle size, maintenance).
+    checklist:
+      - No ESM/CJS interop hazards introduced
+      - No mutation of shared module-level state

package/assets/schema/benchmark.schema.json

@@ -0,0 +1,87 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/stevenzg/edsger-assets/schema/benchmark.schema.json",
+  "title": "Edsger Benchmark Rubric",
+  "description": "A scoring rubric applied to a repository. A `base` rubric is merged with zero or more language overlays to form the effective rubric.",
+  "type": "object",
+  "required": ["id", "name", "version", "kind", "categories"],
+  "additionalProperties": false,
+  "properties": {
+    "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
+    "name": { "type": "string" },
+    "version": { "type": "string" },
+    "kind": { "const": "benchmark" },
+    "extends": {
+      "description": "id of a rubric this overlay merges on top of (usually 'base').",
+      "type": ["string", "null"]
+    },
+    "appliesTo": {
+      "description": "Language ids this rubric targets, or ['*'] for any.",
+      "type": "array",
+      "items": { "type": "string" },
+      "default": ["*"]
+    },
+    "scoreScale": {
+      "description": "Max points each criterion is scored out of (0..max).",
+      "type": "integer",
+      "minimum": 1,
+      "default": 4
+    },
+    "categories": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/definitions/category" }
+    }
+  },
+  "definitions": {
+    "category": {
+      "type": "object",
+      "required": ["id", "name", "weight", "criteria"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
+        "name": { "type": "string" },
+        "weight": {
+          "description": "Relative weight; category weights are normalised to 100 across the effective rubric.",
+          "type": "number",
+          "exclusiveMinimum": 0
+        },
+        "description": { "type": "string" },
+        "criteria": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/definitions/criterion" }
+        }
+      }
+    },
+    "criterion": {
+      "type": "object",
+      "required": ["id", "title", "guidance"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
+        "title": { "type": "string" },
+        "weight": { "type": "number", "exclusiveMinimum": 0, "default": 1 },
+        "guidance": {
+          "description": "What to look for and how to gather evidence in the repo.",
+          "type": "string"
+        },
+        "rubric": {
+          "description": "Anchors describing what each score level looks like.",
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "excellent": { "type": "string" },
+            "good": { "type": "string" },
+            "adequate": { "type": "string" },
+            "poor": { "type": "string" }
+          }
+        },
+        "references": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    }
+  }
+}

package/assets/schema/review.schema.json

@@ -0,0 +1,73 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/stevenzg/edsger-assets/schema/review.schema.json",
+  "title": "Edsger PR Review Standard",
+  "description": "Guidance a reviewer (human or agent) applies to a pull request. A `base` standard is merged with zero or more language overlays.",
+  "type": "object",
+  "required": ["id", "name", "version", "kind", "focusAreas"],
+  "additionalProperties": false,
+  "properties": {
+    "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
+    "name": { "type": "string" },
+    "version": { "type": "string" },
+    "kind": { "const": "review" },
+    "extends": { "type": ["string", "null"] },
+    "appliesTo": {
+      "type": "array",
+      "items": { "type": "string" },
+      "default": ["*"]
+    },
+    "policy": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "blockingSeverities": {
+          "description": "Severities that should block a merge (request changes).",
+          "type": "array",
+          "items": { "enum": ["critical", "high", "medium", "low", "info"] },
+          "default": ["critical", "high"]
+        },
+        "commentStyle": {
+          "enum": ["inline", "summary", "both"],
+          "default": "both"
+        },
+        "maxComments": {
+          "description": "Cap on inline comments to avoid overwhelming the author.",
+          "type": "integer",
+          "minimum": 1,
+          "default": 25
+        },
+        "tone": { "type": "string" }
+      }
+    },
+    "focusAreas": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/definitions/focusArea" }
+    }
+  },
+  "definitions": {
+    "focusArea": {
+      "type": "object",
+      "required": ["id", "title", "guidance"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
+        "title": { "type": "string" },
+        "defaultSeverity": {
+          "enum": ["critical", "high", "medium", "low", "info"],
+          "default": "medium"
+        },
+        "guidance": { "type": "string" },
+        "checklist": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "references": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    }
+  }
+}