Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

4.4 KB
Raw Blame
rules:
    - id: prefer-codegen-api
      message: >-
          Raw `api.<verb>(...)` call outside the API layer. It puts a hand-written URL
          and an unchecked response type at the call site, so a backend change breaks it
          at runtime instead of at compile time. Call the generated function instead:
          `products/<product>/frontend/generated/api.ts` for a product endpoint,
          `frontend/src/generated/core/api.ts` for a core endpoint.

          Agents: invoke the `adopting-generated-api-types` skill
          (`.agents/skills/adopting-generated-api-types/SKILL.md`) for the migration
          workflow. Humans: run `hogli product:maturity --codegen <product>` to see
          the suggested generated function per call site.

          If no generated function covers the endpoint, add its OpenAPI schema
          (`/improving-drf-endpoints`) and run `hogli build:openapi`. Only a URL that the
          server returns (a pagination `next` link, an export download) or a route
          outside the API may stay raw. Mark it with
          `// nosemgrep: prefer-codegen-api -- <reason>` on the line above.
      severity: ERROR
      languages: [typescript, javascript]
      # Namespaced calls (api.signalReports.list()) are a different AST shape and
      # have a backlog in the hundreds, so they live in the WARNING-severity
      # .semgrep/rules/devex/prefer-codegen-api-namespaced.yaml, where the devex
      # job's --baseline-commit pass blocks only the ones a pull request adds.
      pattern-either:
          - pattern: api.get(...)
          - pattern: api.getResponse(...)
          - pattern: api.stream(...)
          - pattern: api.post(...)
          - pattern: api.create(...)
          - pattern: api.createResponse(...)
          - pattern: api.createWithUploadProgress(...)
          - pattern: api.put(...)
          - pattern: api.patch(...)
          - pattern: api.update(...)
          - pattern: api.delete(...)
          - pattern: api.loadPaginatedResults(...)
          # Semgrep's TypeScript parser treats generic-typed calls (api.create<T>())
          # as a different AST shape that AST-level patterns above don't match,
          # so fall back to a regex. Bounds the type args by `(` rather than `>` so
          # nested generics like api.get<PaginatedResponse<Foo>>(...) still match.
          - pattern-regex: '\bapi\.(get|getResponse|stream|post|create|createResponse|createWithUploadProgress|put|patch|update|delete|loadPaginatedResults)<[^(]*>\s*\('
      paths:
          include:
              - '/frontend/src/'
              - '/products/*/frontend/'
          exclude:
              - '**/generated/**'
              # The API layer itself: the transport, the mutator the generated
              # functions call, and the SSE reconnect wrapper over api.stream.
              - '/frontend/src/lib/api.ts'
              - '/frontend/src/lib/api-orval-mutator.ts'
              - '/frontend/src/lib/api-stream.ts'
              # Tests exercise the transport on purpose (retries, re-authentication),
              # and a test is not where the frontend's API contract lives.
              - '**/*.test.ts'
              - '**/*.test.tsx'
              - '**/*.spec.ts'
              - '**/*.spec.tsx'

    - id: prefer-codegen-api-reason
      message: >-
          A `prefer-codegen-api` suppression needs a reason. Write it after ` -- ` on the
          same line, for example
          `// nosemgrep: prefer-codegen-api -- Follows the pagination URL the server returns.`
          The reason tells the next reader whether the raw call is a real exception or
          debt to migrate.
      severity: ERROR
      languages: [typescript, javascript]
      # Semgrep matches a nosemgrep id exactly, so the bare marker that silences
      # prefer-codegen-api on this line does not silence this rule.
      pattern-regex: '(?://|/\*)\s*nosemgrep:[^\n]*?prefer-codegen-api(?![\w-])(?![^\n]*?\s--\s*[^\s*])'
      # Same scope as prefer-codegen-api.
      paths:
          include:
              - '/frontend/src/'
              - '/products/*/frontend/'
          exclude:
              - '**/generated/**'
              - '/frontend/src/lib/api.ts'
              - '/frontend/src/lib/api-orval-mutator.ts'
              - '/frontend/src/lib/api-stream.ts'
              - '**/*.test.ts'
              - '**/*.test.tsx'
              - '**/*.spec.ts'
              - '**/*.spec.tsx'