What Is the Core Library in the CommonGrants Project?

The core library in the CommonGrants project is the @common-grants/core TypeSpec library located in lib/core, which defines the foundational namespace, diagnostics, and utility functions used across the entire ecosystem.

The CommonGrants protocol, developed in the hhs/simpler-grants-protocol repository, relies on a centralized core library to maintain type consistency across its various implementations. This core library in the CommonGrants project serves as the single source of truth for the CommonGrants namespace and provides the building blocks for downstream packages like the TypeScript SDK.

Understanding the @common-grants/core TypeSpec Library

Library Definition and Registration

The core library is instantiated using createTypeSpecLibrary from the @typespec/compiler package. In lib/core/src/lib.ts, the library is defined with the name @common-grants/core and prepares an empty diagnostics object for future extensions:

export const $lib = createTypeSpecLibrary({
  name: "@common-grants/core",
  diagnostics: {
    // We'll add diagnostics later if needed
  },
} as const);

Exported Utilities for Diagnostics

Beyond the library instance, the core exports helper functions for diagnostic reporting. The same file extracts reportDiagnostic and createDiagnostic from the library instance:

export const { reportDiagnostic, createDiagnostic } = $lib;

Integration Points and Usage Across the Ecosystem

Entry Point Exports

The main entry point at lib/core/src/index.ts re-exports the library instance, making it available for external consumption:

export { $lib } from "./lib.js";

SDK Implementation References

Downstream consumers like the TypeScript SDK reference namespaces defined by the core library. The SDK's Zod schemas map to CommonGrants.Types, CommonGrants.Filters, and CommonGrants.Fields, all of which originate from the core library definitions. For example, in lib/ts-sdk/src/schemas/zod/types.ts:

/**
 * Types for the CommonGrants.Types namespace in the @common-grants/core library.
 */
export const GrantType = z.enum(["grant", "subgrant"]);

Summary

• The core library in the CommonGrants project is the @common-grants/core TypeSpec package located in lib/core.
• It is defined in lib/core/src/lib.ts using createTypeSpecLibrary and exports $lib, reportDiagnostic, and createDiagnostic.
• The library establishes the CommonGrants namespace used by the TypeScript SDK and other downstream implementations.
• It serves as the foundational layer for type definitions, diagnostics, and utility functions across the entire protocol ecosystem.

Frequently Asked Questions

What file defines the core library in the CommonGrants project?

The core library is defined in lib/core/src/lib.ts, where createTypeSpecLibrary instantiates the @common-grants/core library with its configuration and diagnostic definitions.

How does the TypeScript SDK use the core library?

The SDK references namespaces defined by the core library—such as CommonGrants.Types, CommonGrants.Filters, and CommonGrants.Fields—to construct Zod schemas that validate data structures against the protocol specifications.

What utilities does the core library export for error handling?

The core library exports reportDiagnostic and createDiagnostic functions from lib/core/src/lib.ts, which provide standardized mechanisms for creating and reporting compiler diagnostics throughout the TypeSpec ecosystem.

Where is the core library entry point for external imports?

External modules import the core library through lib/core/src/index.ts, which re-exports the $lib instance, making the library's symbols available to downstream packages like the TypeScript SDK.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}