[dev-tool] Add snippets extraction #31143
Open
+1,246
−206
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Packages impacted by this PR
Issues associated with this PR
Describe the problem that is addressed by this PR
This PR implements a new dev-tool command:
dev-tool run update-snippets
.This command looks for code fences in markdown files and JSDoc comments, and updates them with the contents of test methods in a file named
snippets.spec.ts
.For example, the following fence indicates that the contents of a test named "new_configurationclient" should be used:
After running
dev-tool run update-snippets
, the contents of the snippet will be populated:To accomplish this, the command uses the TypeScript compiler API to extract and transpile snippets from
snippets.spec.ts
. Snippets are the contents of calls to theit
function. If syntax with the shapeit(<literal string>, <function with block>)
appears insnippets.spec.ts
, it will be considered a snippet that is valid for injection.("Function with block" means either a
function () { ... }
expression or an arrow function with a block on the arrow side (() => { ... }
). An arrow function that has an expression on the right hand side (() => (...)
) will not be recognized.)For example:
The transpiler automatically "cleans" and validates the snippet using similar techniques as the sample transpiler. As a result, it enforces the same syntactic rules that the sample transpiler does. In addition to those, it removes references to
process.env
(if an alternative is specified), removes compiler pragmas like// @ts-ignore
, and automatically inserts imports for symbols that the snippet uses. So in the above snippet, imports forConfigurationClient
andDefaultAzureCredential
are required, automatically detected, and injected into the resulting snippet.Snippets without
snippet:${name}
tags are errors when using this command, so a package must be fully migrated to use it.What are the possible designs available to address the problem? If there are more than one possible design, why was the one in this PR chosen?
Are there test cases added in this PR? (If not, why?)
Provide a list of related PRs (if any)
Command used to generate this PR:**(Applicable only to SDK release request PRs)
Checklists