feat(compiler): expose suppression inspection APIs

[Timothee Guerin (timotheeguerin)]

Suppression reporting tools currently reimplement directive parsing, declaration-context traversal, and YAML extraction to inspect files without compiling a project. Expose this information directly from the compiler, and let tools inspecting compiled programs read observed usage from the existing tracker.

import { collectLinterDisables } from "@typespec/compiler";
import { collectSuppressions, getSuppressions, parse } from "@typespec/compiler/ast";

const suppressions = collectSuppressions(parse(source));
const [disables, diagnostics] = collectLinterDisables(configText);
const observed = getSuppressions(program); // Each result includes `used`.

Inline results include the directive, attached node, source location, and structured declaration context. Compiled results reuse the internal tracker and snapshot whether each project suppression has matched a diagnostic so far, including rejected attempts to suppress errors. used: false does not establish that a suppression is unnecessary under other settings: a rule may be disabled, a source unavailable, an emitter skipped, or compilation stopped early. These limits are documented in the API comments.

Config results include local rule disables, justifications, key locations, and diagnostics. Parse-only APIs preserve written rule codes without loading libraries or following inherited configuration; reporting identities remain consumer-defined.

Addresses the compiler-side work for Azure/typespec-azure#5030. Consumer showcase: Azure/azure-rest-api-specs#46983.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@typespec/compiler@12095

commit: c849b28

[azure-sdk-automation]

You can try these changes here

🛝 Playground	🌐 Website	🛝 VSCode Extension

[github-actions]

All changed packages have been documented.

• ✅ @typespec/compiler

Show changes

@typespec/compiler - feature ✏️

Inspect inline suppressions and local linter disables without compiling a project. Inline results include declaration context and source locations; config results include rule-key locations and diagnostics. For compiled programs, inspect whether each project suppression matched a diagnostic using getSuppressions.,> ,> ts,> import { collectLinterDisables } from "@typespec/compiler";,> import { collectSuppressions, getSuppressions, parse } from "@typespec/compiler/ast";,> ,> const script = parse(source);,> const suppressions = collectSuppressions(script);,> const [disables, diagnostics] = collectLinterDisables(configText);,> const observedSuppressions = getSuppressions(program); // Includes a `used` flag.,> ,> ,> Usage is a snapshot of diagnostics matched so far in that compilation, including rejected attempts to suppress errors. An unmatched suppression may be needed under other settings: its rule could be disabled, its diagnostic source unavailable, its emitter skipped, or compilation could stop before the relevant stage runs.

[Copilot]

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Copilot review overview

Review effort: Lite
Findings: 1 · 3

Open (4)

• This doc page previously called out the lack of an API for suppression resolution; that section is… · New
• The scope-building strategy allocates a new array ([...parentScope, entry]) for every node that… · New
• The scope-building strategy allocates a new array ([...parentScope, entry]) for every node that… · New
• parseYaml() now manually constructs the return tuple instead of using the diagnostic collector’s… · New

What changed in this PR

Expose compiler APIs that let tools inspect inline #suppress directives and config-based linter.disable entries without compiling a full project.

Changes:

• Added collectSuppressions() (AST-level) with source locations and declaration-context scope, exported via @typespec/compiler/ast.
• Added collectLinterDisables() (config YAML-level) with key locations + diagnostics, exported from @typespec/compiler.
• Refactored suppression tracking to reuse the AST collector; added tests and changelog entry.

File	Description
website/​src/​content/​docs/​docs/​language-basics/​directives.md	Removes outdated statement about lack of an API for suppressions.
packages/​compiler/​src/​ast/​suppressions.ts	Introduces AST suppression collection with scope + location.
packages/​compiler/​src/​ast/​index.ts	Exports new suppression inspection API/types.
packages/​compiler/​src/​config/​linter-disables.ts	Adds YAML config linter.disable extraction with locations + diagnostics.
packages/​compiler/​src/​yaml/​parser.ts	Adds parseYamlDocument() to expose raw YAML document for inspection use-cases.
packages/​compiler/​src/​core/​directives.ts	Centralizes directive parsing for reuse.
packages/​compiler/​src/​core/​suppression-tracking.ts	Reuses collectSuppressions() for project suppression tracking.
packages/​compiler/​src/​index.ts	Exports collectLinterDisables as a public compiler API.
packages/​compiler/​test/​ast/​suppressions.test.ts	Adds coverage for new AST suppression collector behavior.
packages/​compiler/​test/​config/​linter-disables.test.ts	Adds coverage for linter disable extraction, locations, and diagnostics.
.chronus/​changes/​compiler-suppression-inspection.md	Adds changelog entry + usage snippet.

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🟢 Approval recommended

The public APIs are documented, changeset-covered, and exercised across success, invalid-input, alias, and compilation-state scenarios.

Review effort: Balanced
Findings: None

Resolved since last review (4)

• This doc page previously called out the lack of an API for suppression resolution; that section is…
• parseYaml() now manually constructs the return tuple instead of using the diagnostic collector’s…
• The scope-building strategy allocates a new array ([...parentScope, entry]) for every node that…
• The scope-building strategy allocates a new array ([...parentScope, entry]) for every node that…