[dev-tool] Add snippets extraction

[mpodwysocki]

Packages impacted by this PR

• @azure/dev-tool

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:

```js snippet:new_configurationclient
```

After running dev-tool run update-snippets, the contents of the snippet will be populated:

```js snippet:new_configurationclient
import { ConfigurationClient } from "@azure/template";
import { DefaultAzureCredential } from "@azure/identity";

const client = new ConfigurationClient(
  "<app configuration endpoint>",
  new DefaultAzureCredential()
);
```

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 the it function. If syntax with the shape it(<literal string>, <function with block>) appears in snippets.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:

  it("new_configurationclient", function () {
    // @ts-ignore
    const client = new ConfigurationClient(
      process.env.ENDPOINT ?? "<app configuration endpoint>",
      new DefaultAzureCredential()
    );
  });

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 for ConfigurationClient and DefaultAzureCredential 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)

• [dev-tool] Inline snippet extraction. #24536

Command used to generate this PR:**(Applicable only to SDK release request PRs)

Checklists

• Added impacted package name to the issue description
• Does this PR needs any fixes in the SDK Generator?** (If so, create an Issue in the Autorest/typescript repository and link it here)
• Added a changelog (if necessary)

[azure-sdk]

API change check

API changes are not detected in this pull request.

[jeremymeng]

Looks great for a v1!

Can you please log issue for potential improvements? For example,

• centralized location to get the logger sample (maybe an option to specify package path override?)
• move linting overrides to our eslint-plugin for the snippets file
• possible to centralize the exclusion of snippets file in dev-tool/centralized config?

[maorleger]

Most of the changes look great and I love the improvement. I want to avoid ts-ignore everywhere if at all possible and I would love to be able to name the tests whatever I want. To that end, I suggested an alternative in how we define snippet blocks - curious what you think!