GO — Healthy across the board

• Last commit today
• 15 active contributors
• Distributed ownership (top contributor 29% of recent commits)
• MIT licensed
• CI configured
• Tests present

_{Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests}

TypeSpec is a domain-specific language (DSL) for defining cloud service APIs and data shapes that can be compiled to multiple formats (OpenAPI 3.0, gRPC, protocol buffers, client/server code in Java/C#/Python/TypeScript). It acts as a single source of truth for API design, with built-in support for REST, HTTP semantics, and extensible emitters to generate documentation, SDKs, and service stubs across language ecosystems. Monorepo with language-specific emitter packages: packages contain the TypeSpec compiler (TypeScript/Node-based), with separate packages for @typespec/http, @typespec/rest, @typespec/openapi3 libraries. Emitters for C# (@typespec/http-client-csharp), Java, and Python live alongside the core compiler. VSCode and Visual Studio extensions are shipped separately. Examples and playground (Astro-based, 84K LoC) demonstrate end-to-end workflows.

Cloud API designers, platform teams, and SDK maintainers at enterprises (especially Azure ecosystem users) who need to version and generate consistent API specifications and client libraries across multiple programming languages without manually maintaining OpenAPI specs, Swagger docs, and language-specific stubs separately.

Production-ready and actively developed. The repo shows heavy recent activity (late April 2026 commits visible in .chronus/changes), comprehensive multi-language emitter support (Java 28M LoC, TypeScript 9.7M, C# 8.3M), and VS Code/VS extensions in official marketplaces. Test coverage is implied by the testing infrastructure and language-specific test fixes (Python, Windows-specific tests) in recent changes.

Moderate risk: broad dependency surface (Java, C#, Python, TypeScript, Node toolchain all required for full local development), and Microsoft-maintained single-source-of-truth risk—but community-supported per README. Recent fixes for 'lsp-unhandled-exceptions', 'compiler-server-null-crashes', and parallel NuGet build issues suggest active bug discovery. Breaking changes appear managed via the .chronus/changes changelog system.

Active refinement across multiple areas: Python generator improvements (fixing wire-name padding, API version docs, CI fixes), HTTP client Java/Node dependency updates, playground UX enhancements, linter rule option support, protocol buffer optional field handling, and Windows-specific fixes (cursor flicker, sensitive word tests). Recent changes suggest focus on stability, cross-platform compatibility, and Python/C# SDK generation quality.

git clone https://github.com/microsoft/typespec.git
cd typespec
npm install
npm run build
npm run test

Daily commands:

npm run build              # Compile TypeSpec compiler and packages
npm run test              # Run test suite
npm run test -- --filter # Run specific test suites
npm run dev               # Watch mode for development
tsp --version             # Verify CLI installation

• .github/workflows/ci.yml — Primary CI/CD pipeline orchestrating all build, test, and release workflows across the TypeSpec monorepo
• .chronus/config.yaml — Change management and versioning configuration that tracks all package releases and breaking changes
• .github/copilot-instructions.md — AI-assisted development guidelines defining coding standards and architectural conventions for contributors
• .editorconfig — Enforces consistent code formatting rules (indentation, line endings, charset) across all contributors
• .github/CODEOWNERS — Defines code ownership and required reviewers for each component, ensuring architectural coherence
• .devcontainer/devcontainer.json — Standardized development environment specification ensuring all contributors work in identical conditions
• .github/dependabot.yml — Automated dependency management and security updates critical for maintaining TypeSpec's large dependency tree

• GitHub Actions CI pipeline (YAML workflows, GitHub API, Node.js runners) — Orchestrates all tests, linting, compilation, security scanning, and release automation for every commit
  • Failure mode: Pipeline blocks PRs; failures prevent merges to main and halt releases
• Chronus versioning system (YAML change files, Node.js versioning logic) — Tracks breaking changes, feature additions, and fixes; auto-generates changelogs; bumps package versions per SemVer
  • Failure mode: Incorrect version bumps lead to dependency conflicts in monorepo; changelog inconsistencies confuse users
• Linter & formatter enforcement —

Add a new workflow automation

1. Create the workflow YAML file in .github/workflows/ following the pattern of ci.yml (.github/workflows/ci.yml)
2. Define workflow triggers (on: push, pull_request, schedule) and job matrix if needed (.github/workflows/README.md)
3. Register the workflow in GitHub Actions by committing to main branch (.github/workflows)

Add a new language-specific HTTP client emitter

1. Create emitter instructions file following the pattern of existing http-client-*.instructions.md (.github/instructions/http-client-csharp.instructions.md)
2. Add emitter-specific skill definition in .github/skills/ for automation (.github/skills/http-client-python-bump-and-release/SKILL.md)
3. Update CI workflow to run emitter tests and add language to matrix builds (.github/workflows/ci.yml)
4. Define dependency tracking in .github/dependabot.yml for language-specific package managers (.github/dependabot.yml)

Add a new policy for issue/PR automation

1. Create YAML policy file in .github/policies/ following triage.generated.yml structure (.github/policies/prs.triage.generated.yml)
2. Define trigger conditions and auto-label/auto-comment actions (.github/policies/issues.needs-info.yml)
3. Register policy by committing to main; GitHub automatically applies it to matching issues/PRs (.github/policies)

Add a new code ownership rule

1. Edit CODEOWNERS to add path patterns and required reviewers (.github/CODEOWNERS)
2. Ensure reviewer GitHub handles are valid organization members with write access (.github/CODEOWNERS)
3. Commit change; GitHub will enforce reviews on matching PRs automatically (.github/CODEOWNERS)

• GitHub Actions workflows (YAML) — Native to GitHub repositories; no external CI infrastructure required; tightly integrated with PRs and release automation
• Chronus (change management) — Manages version bumps and changelogs from structured change files; automates semantic versioning across monorepo packages
• DevContainer (Docker + JSON config) — Ensures consistent development environment across all contributors; eliminates 'works on my machine' issues
• GitHub CodeQL (security scanning) — Deep static analysis for TypeScript/JavaScript security vulnerabilities; integrated with PR gating
• Dependabot (dependency automation) — Monitors npm, NuGet, and language-specific package managers; auto-creates PRs for updates; handles security advisories

• Monorepo structure with per-package versioning (via Chronus)

  • Why: Enables teams to ship emitters and tools at different cadences; reduces coupling between core language and extensions
  • Consequence: Complex changelog management; requires careful coordination when packages have interdependencies

• Agentic workflows (AI-assisted automation) alongside traditional CI

  • Why: Allows code generation, testing, and version bumps to be driven by LLMs for faster iteration on tooling
  • Consequence: Introduces non-determinism and requires careful prompt engineering; adds layer of indirection for debugging

• CodeQL-only security scanning (no third-party SAST)

  • Why: Minimal external dependencies; built into GitHub; scales across large monorepo
  • Consequence: Limited to language patterns CodeQL understands; misses domain-specific vulnerabilities (e.g., emitter-specific issues)

• Real-time collaborative editing (TypeSpec is a DSL, not a live IDE)
• Package hosting or distribution (relies on npm, NuGet, PyPI registries)
• Runtime execution of TypeSpec code (compile-only language for schema generation)
• Authentication/authorization enforcement (TypeSpec itself is compile-time; delegated to emitters)
• Cross-platform binary distribution (Node.js + npm is primary distribution channel)

Multi-language dev environment required: Full local development needs Node.js 22+ (recent change), Python 3.10+, .NET/C# SDK, and Java toolchain—not all may be on PATH. Python generator quirks: Recent fixes for 'keep-setup.py-coercion' and 'black-linesep-windows' suggest platform-specific code generation edge cases. Emitter versioning: Each language emitter (@typespec/http-client-csharp, etc.) has separate versioning and release cycles; watch dependencies. Windows-specific test failures: Recent changes like 'fix-windows-cursor-flicker' and 'fix-windows-sensitive-word-test' indicate Windows path/character encoding gotchas in tests.

• Semantic Analysis / Symbol Resolution — TypeSpec compiler performs multi-pass semantic analysis to resolve type references, validate constraints, and build a symbol table before emitter execution; understanding this pass is critical for debugging type-related errors and emitter correctness
• Emitter Framework / Plugin Architecture — TypeSpec's core strength is the extensible emitter system that lets you target any output format (OpenAPI, Protobuf, client code); you must understand how emitters register, traverse the type graph, and generate output to create custom emitters or fix existing ones
• Multi-Target Code Generation — Single TypeSpec definition compiles to OpenAPI 3.0, C#, Java, Python, Protobuf, and more; managing divergent output semantics (e.g., Python's snake_case vs C#'s PascalCase) requires understanding language-specific emitters and wire format conventions
• Constraint Validation & Decorators — TypeSpec's type system uses decorators (@minLength, @maxValue, @route, etc.) to attach constraints and metadata; emitters must interpret these correctly to generate validating client/server code
• OpenAPI / REST HTTP Semantics — The @typespec/http and @typespec/rest libraries map TypeSpec models to HTTP verbs, status codes, headers, and request/response bodies; emitters must correctly translate these to generate type-safe client code
• Protocol Buffer Wire Format & Serialization — Recent 'protobuf-optional' fix indicates TypeSpec must emit proto3 semantics correctly; understanding protobuf field numbering, oneof groups, and optional field evolution is essential for maintaining backward compatibility
• Language Server Protocol (LSP) / IDE Integration — TypeSpec provides LSP for VS Code and Visual Studio; recent fixes like 'fix-lsp-unhandled-exceptions' show LSP stability is critical for IDE experience; understanding the LSP handshake and hover/completion logic helps debug editor crashes

• OAI/OpenAPI-Specification — TypeSpec compiles to OpenAPI 3.0 via @typespec/openapi3; understanding the spec itself is essential for debugging emitter output
• Azure/azure-sdk-for-python — Major downstream consumer of TypeSpec Python generator; emitter must produce code compatible with Azure SDK patterns and conventions
• Azure/azure-sdk-for-csharp — Primary user of @typespec/http-client-csharp emitter; C# code generation must follow Azure SDK style and testing patterns
• protocolbuffers/protobuf — TypeSpec supports protocol buffer emission via dedicated emitter; understanding protobuf wire format and optional field semantics (recent 'protobuf-optional' fix) is relevant
• microsoft/kiota — Related Microsoft project for code generation from OpenAPI; both compete and complement in the API-first code generation space

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for Chronus changelog generation across language emitters

The repo has 60+ changelog entries in .chronus/changes/ but no visible integration tests verifying that changelog entries are correctly parsed and included in release notes for different emitters (Python, C#, Java, etc.). This is critical since the changelog system appears to be the mechanism for tracking changes across multiple language-specific packages. A new contributor could add tests that verify changelog entries flow through to generated release artifacts.

• [ ] Create test file: packages/typespec-test-utils/src/chronus-integration.test.ts
• [ ] Add test cases that parse entries from .chronus/changes/ and verify they're correctly categorized by package
• [ ] Add validation that all dated changelog entries have proper frontmatter (package, type, date)
• [ ] Add tests for emitter-specific changelog filtering (e.g., Python emitter only includes relevant entries)
• [ ] Run against the 60+ existing changelog entries to ensure none are malformed

Add GitHub Action workflow for validating dependency consistency across polyrepo packages

The repo uses a monorepo structure with multiple language emitters (Python, C#, Java, Node.js) each with their own dependency trees. The example shows @typespec/http-client-csharp at version 1.0.0-alpha.20260310.2 - there's no visible CI workflow to prevent version mismatches or security issues across packages. A new contributor could create a workflow that validates dependency versions are pinned consistently and scans for known vulnerabilities per language ecosystem.

• [ ] Create .github/workflows/validate-dependencies.yml
• [ ] Add step to scan Python dependencies (packages/python-*/requirements.txt) using pip-audit
• [ ] Add step to validate Node.js dependencies across packages using npm audit
• [ ] Add step to validate C# dependencies using NuGet security scanning
• [ ] Add step to check for version mismatches in cross-package dependencies (e.g., shared typespec core versions)
• [ ] Configure to run on PR and report findings as blocking checks

Add comprehensive test coverage for glob normalization across Windows/Unix paths

The changelog entry 'fix-glob-normalize-2026-3-14-12-2-56.md' suggests recent bugs with path handling across platforms. The file structure shows dev containers and Windows-specific fixes (fix-windows-cursor-flicker, fix-windows-sensitive-word-test), indicating cross-platform path issues. A new contributor could add a parametrized test suite that validates glob patterns and path normalization work identically on Windows and Unix-like systems.

• [ ] Create packages/compiler/test/glob-normalization.test.ts with platform-agnostic assertions
• [ ] Add test cases for: relative paths, absolute paths, UNC paths (Windows), symlinks, nested glob patterns
• [ ] Add test fixtures in test/fixtures/glob-test-files/ covering edge cases
• [ ] Implement tests that run on both Windows and Unix environments using @jest/globals platform detection
• [ ] Add regression tests for the specific glob bugs mentioned in recent changelogs
• [ ] Validate path separator normalization (/ vs ) is transparent to users

• Add integration tests for Python SDK generation with nested model inheritance (observed gaps in 'python-integrationTest' and 'python-module-loading' recent fixes suggest test coverage is incomplete for complex scenarios)
• Document the @typespec/http, @typespec/rest, and @typespec/openapi3 decorator API surface in a searchable registry (README examples exist but no comprehensive API docs file for new emitter authors)
• Create example projects demonstrating TypeSpec → Python client + C# server co-generation (current examples are REST-generic; Azure SDK users need multi-language end-to-end walkthroughs)

The TypeSpec repository demonstrates generally good security posture with proper security reporting guidelines in place. The main concerns are around dependency management practices (local file dependencies without versioning and pre-release versions in production dependencies). The codebase structure shows appropriate separation of concerns with linting frameworks and configuration management. No critical vulnerabilities were identified in the accessible artifacts, but the dependency management practices should be reviewed and tightened to prevent supply chain risks. The repository appears to follow Microsoft's security guidelines and best practices for open-source projects.

• Medium · Local File Dependency Without Version Pinning — package.json - dependencies.logging-plugin. The package.json contains a local file dependency 'logging-plugin' that references '../plugins/logging' without version constraints. This can lead to unexpected changes if the local dependency is modified without proper version control. Fix: Pin the local dependency to a specific version or commit hash. Consider using npm workspaces or monorepo tools (already in use via .chronus) to manage local dependencies with explicit versioning.
• Low · Pre-release Dependency Version — package.json - dependencies.@typespec/http-client-csharp. The dependency '@typespec/http-client-csharp' is pinned to a pre-release version '1.0.0-alpha.20260310.2', which may contain experimental features or unresolved bugs not present in stable releases. Fix: Upgrade to a stable release version when available. If pre-release use is necessary, document the rationale and establish a timeline for upgrading to stable versions.
• Low · Incomplete SECURITY.md — SECURITY.md. The SECURITY.md file appears truncated or incomplete, potentially missing important security contact information or vulnerability disclosure procedures that should be clearly documented. Fix: Ensure the SECURITY.md file is complete with full Microsoft Security Response Center (MSRC) contact details and clear vulnerability reporting instructions.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/microsoft/typespec shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live microsoft/typespec repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/microsoft/typespec.

What it runs against: a local clone of microsoft/typespec — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in microsoft/typespec | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of microsoft/typespec. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/microsoft/typespec.git
#   cd typespec
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of microsoft/typespec and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "microsoft/typespec(\\.git)?\\b" \\
  && ok "origin remote is microsoft/typespec" \\
  || miss "origin remote is not microsoft/typespec (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f ".github/workflows/ci.yml" \\
  && ok ".github/workflows/ci.yml" \\
  || miss "missing critical file: .github/workflows/ci.yml"
test -f ".chronus/config.yaml" \\
  && ok ".chronus/config.yaml" \\
  || miss "missing critical file: .chronus/config.yaml"
test -f ".github/copilot-instructions.md" \\
  && ok ".github/copilot-instructions.md" \\
  || miss "missing critical file: .github/copilot-instructions.md"
test -f ".editorconfig" \\
  && ok ".editorconfig" \\
  || miss "missing critical file: .editorconfig"
test -f ".github/CODEOWNERS" \\
  && ok ".github/CODEOWNERS" \\
  || miss "missing critical file: .github/CODEOWNERS"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/microsoft/typespec"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.