@coderifts/contract-path

Path-name classifier for API contract artifacts. Single list. Zero runtime dependencies.

This is the same classifier the CodeRifts merge gate and the generic derivation: "server" path (ID637 6b) use. Hosts (OpenAI-Agents guardrail, hooks, other packages) import it from npm instead of reaching into the app checkout.

Classification is path-name only. The module does not read file content.

npm install @coderifts/contract-path

const { looksLikeContractPath, typeForPath } = require('@coderifts/contract-path');
// or: import { looksLikeContractPath, typeForPath } from '@coderifts/contract-path';

if (looksLikeContractPath(filename)) {
  const type = typeForPath(filename); // 'openapi' | 'asyncapi' | 'graphql' | 'grpc' | 'mcp_manifest'
}

Call looksLikeContractPath first. typeForPath is a mapping, not a gate: typeForPath('package.json') returns 'openapi' even though looksLike is false.

What counts

A path is a contract artifact when all of:

1. It is not under node_modules/ or vendor/.
2. Its extension matches .(ya?ml|json|graphql|gql|proto) (case-insensitive).
3. Its path-name contains openapi, swagger, asyncapi, or mcp, or the extension is .graphql / .gql / .proto.

| Path | looksLike | type (if looksLike) | |---|---|---| | api/openapi.yaml | true | openapi | | swagger.json | true | openapi | | asyncapi.yaml | true | asyncapi | | schema.graphql | true | graphql | | svc/user.proto | true | grpc | | mcp.json / .well-known/mcp.json | true | mcp_manifest | | package.json | false | — | | tsconfig.json | false | — | | package-lock.json / pnpm-lock.yaml | false | — | | .github/workflows/ci.yml | false | — | | README.md / src/index.js | false | — | | node_modules/openapi.yaml | false | — | | vendor/openapi.yaml | false | — |

Existing behaviour, not a new rule: .github/workflows/openapi.yaml is true today because the file name contains openapi. Do not invent a workflow exclusion in this module.

Dual module

CJS (index.cjs) is the algorithm. ESM (index.mjs) re-exports it via createRequire so there is one list, not two.