pkg:snippets: new package! by kevmoo · Pull Request #2411 · dart-lang/tools

kevmoo · 2026-05-20T03:51:58Z

Migrate the excerpter package from dart-lang/labs to dart-lang/tools and rename to pkg:snippets which is easier to remember and type and we can take over the existing thingy: https://pub.dev/packages/snippets

Core Package & Setup:

Ported all core libraries, executable entry points, and tests to pkgs/excerpter.
Adapted constraints to target Dart SDK ^3.12.0 and replaced the site-specific analysis_defaults with package:dart_flutter_team_lints.
Structured a clean library programmatic usage example in example/main.dart.
Exposed code ownership in .github/CODEOWNERS.
Set up GitHub Actions CI workflow in .github/workflows/excerpter.yaml.
Set up labeler patterns in .github/labeler.yml.
Registered the excerpter package in the root README.md.

Migrate the excerpter package from dart-lang/labs to dart-lang/tools. Core Package & Setup: - Ported all core libraries, executable entry points, and tests to `pkgs/excerpter`. - Adapted constraints to target Dart SDK `^3.9.0` and replaced the site-specific `analysis_defaults` with `package:dart_flutter_team_lints`. - Structured a clean library programmatic usage example in `example/main.dart`. - Exposed code ownership in `.github/CODEOWNERS`. - Set up GitHub Actions CI workflow in `.github/workflows/excerpter.yaml`. - Set up labeler patterns in `.github/labeler.yml`. - Registered the `excerpter` package in the root `README.md`. Core Bug Fix & Enhancements: - Fixed a `RangeError` crash inside the code block parser loop in `inject.dart` when dealing with unclosed blocks at the end of a file. - Implemented native tracking of static code blocks to ignore illustrative `<?code-excerpt` snippets inside fenced Markdown regions, avoiding visual backslash prefix workarounds. - Formatted all files to adhere strictly to the 80-column limit. Testing & Robustness: - Added dedicated unit tests for exceptional extractor parser failures in `test/extractor_test.dart` and `test/injection_test.dart`. - Migrated temporary directory setups to use `package:test_descriptor` for platform-agnostic, isolated sandbox tests. - Added an automated validation test in `test/cli_test.dart` to guarantee the `README.md` options table stays in perfect sync with the CLI `ArgParser` definition. - Achieved 87.6% core statement coverage (including 100% coverage on `extract.dart` and `update.dart`).

github-actions · 2026-05-20T03:52:50Z

Package publishing

Package	Version	Status	Publish tag (post-merge)
package:api_summary	0.1.0-wip	WIP (no publish necessary)
package:bazel_worker	1.1.5	already published at pub.dev
package:benchmark_harness	2.4.0	already published at pub.dev
package:boolean_selector	2.1.2	already published at pub.dev
package:browser_launcher	1.2.0-wip	WIP (no publish necessary)
package:cli_config	0.2.1-wip	WIP (no publish necessary)
package:cli_util	0.5.1	already published at pub.dev
package:clock	1.1.3-wip	WIP (no publish necessary)
package:code_builder	4.12.0-wip	WIP (no publish necessary)
package:coverage	1.15.0	already published at pub.dev
package:csslib	1.0.2	already published at pub.dev
package:extension_discovery	2.1.0	already published at pub.dev
package:file	7.0.2-wip	WIP (no publish necessary)
package:file_testing	3.1.0-wip	WIP (no publish necessary)
package:glob	2.1.3	already published at pub.dev
package:graphs	2.4.0-wip	WIP (no publish necessary)
package:html	0.15.7-wip	WIP (no publish necessary)
package:io	1.1.0-wip	WIP (no publish necessary)
package:json_rpc_2	4.1.0	already published at pub.dev
package:markdown	7.4.0	ready to publish	`markdown-v7.4.0`
package:mime	2.1.0-wip	WIP (no publish necessary)
package:oauth2	2.0.5	already published at pub.dev
package:package_config	2.3.0-wip	WIP (no publish necessary)
package:pool	1.5.3-wip	WIP (no publish necessary)
package:process	5.0.5	(error) pubspec version (5.0.5) and changelog (5.0.6-wip) don't agree
package:pub_semver	2.2.0	already published at pub.dev
package:pubspec_parse	1.6.0-wip	WIP (no publish necessary)
package:snippets	0.1.0-wip	WIP (no publish necessary)
package:source_map_stack_trace	2.1.3-wip	WIP (no publish necessary)
package:source_maps	0.10.14-wip	WIP (no publish necessary)
package:source_span	1.10.2	already published at pub.dev
package:sse	4.2.0	already published at pub.dev
package:stack_trace	1.12.2-wip	(error) pubspec version (1.12.2-wip) and changelog (1.12.2-dev) don't agree
package:stream_channel	2.1.4	already published at pub.dev
package:stream_transform	2.1.2-wip	WIP (no publish necessary)
package:string_scanner	1.4.2-wip	WIP (no publish necessary)
package:term_glyph	1.2.3-wip	WIP (no publish necessary)
package:test_reflective_loader	0.6.0	ready to publish	`test_reflective_loader-v0.6.0`
package:timing	1.0.2	already published at pub.dev
package:unified_analytics	8.0.15	ready to publish	`unified_analytics-v8.0.15`
package:watcher	1.2.2-wip	WIP (no publish necessary)
package:yaml	3.1.4-wip	WIP (no publish necessary)
package:yaml_edit	2.2.4	already published at pub.dev

Documentation at https://github.com/dart-lang/ecosystem/wiki/Publishing-automation.

github-actions · 2026-05-20T03:53:08Z

PR Health

API leaks ✔️

The following packages contain symbols visible in the public API, but not exported by the library. Export these symbols or remove them from your publicly visible API.

Package	Leaked API symbol	Leaking sources

This check can be disabled by tagging the PR with skip-leaking-check.

Unused Dependencies ✔️

Package	Status
snippets	✔️ All dependencies utilized correctly.

For details on how to fix these, see dependency_validator.

This check can be disabled by tagging the PR with skip-unused-dependencies-check.

License Headers ✔️

// Copyright (c) 2026, the Dart project authors. Please see the AUTHORS file
// for details. All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.

Files
no missing headers

All source files should start with a license header.

Unrelated files missing license headers

Files
pkgs/bazel_worker/benchmark/benchmark.dart
pkgs/coverage/lib/src/coverage_options.dart
pkgs/html/example/main.dart
pkgs/pubspec_parse/test/git_uri_test.dart
pkgs/watcher/test/custom_watcher_factory_test.dart

This check can be disabled by tagging the PR with skip-license-check.

Changelog Entry ✔️

Package	Changed Files

Changes to files need to be accounted for in their respective changelogs.

This check can be disabled by tagging the PR with skip-changelog-check.

Breaking changes

⚠️

Package	Change	Current Version	New Version	Needed Version	Looking good?
snippets	Breaking	0.4.3	0.1.0-wip	We got a pre release. We only check if there are any changes. Got "0.1.0-wip" expected > "0.4.3" (pre-release but changes)	⚠️

This check can be disabled by tagging the PR with skip-breaking-check.

Coverage

⚠️

File	Coverage
pkgs/snippets/bin/snippets.dart	💔 Not covered
pkgs/snippets/example/main.dart	💔 Not covered
pkgs/snippets/lib/snippets.dart	💔 Not covered
pkgs/snippets/lib/src/extract.dart	💚 93 %
pkgs/snippets/lib/src/inject.dart	💚 75 %
pkgs/snippets/lib/src/transform.dart	💚 98 %
pkgs/snippets/lib/src/update.dart	💚 100 %
pkgs/snippets/test_data/example/dartdoc.dart	💔 Not covered
pkgs/snippets/test_data/example/plaster.dart	💔 Not covered
pkgs/snippets/test_data/example/simple_main.dart	💔 Not covered
pkgs/snippets/test_data/example/simple_region.dart	💔 Not covered
pkgs/snippets/test_data/example/transforms.dart	💔 Not covered

This check for test coverage is informational (issues shown here will not fail the PR).

This check can be disabled by tagging the PR with skip-coverage-check.

gemini-code-assist

Code Review

This pull request introduces the excerpter package, a tool for synchronizing code excerpts in Markdown files with source code regions. It includes a CLI, a programmatic API, and various text transformations. Feedback focuses on improving the robustness of the instruction parser (specifically handling escaped quotes and delimiters), ensuring consistency between the documentation and regex for region names, and optimizing performance by pre-compiling regexes and sharing the extraction cache across multiple files.

kevmoo · 2026-05-20T04:04:36Z

/gemini review

gemini-code-assist

Code Review

This pull request introduces the excerpter package to the monorepo, a tool designed to synchronize code excerpts in Markdown files with regions defined in source code. The reviewer identified several areas for improvement, including a potential RangeError in inject.dart when handling short lines and a bug in the shared indentation logic that fails when excerpts contain empty lines. Additionally, the feedback suggests using the path package for more robust file extension detection and updating the README.md to reflect the package's new repository location and bug tracker links.

kevmoo · 2026-05-20T04:35:43Z

/gemini review

gemini-code-assist

Code Review

This pull request introduces a new package, excerpter, designed to update code excerpts in Markdown documentation from source files. The changes include the package structure, CLI implementation, and necessary configuration files. The review identified a discrepancy between the SDK version in the PR description and the pubspec.yaml, suggested simplifying argument parsing and error handling in the CLI, and pointed out an unnecessary await in pkgs/markdown/tool/update_shared.dart that conflicts with the unnecessary_await_in_return lint rule.

kevmoo · 2026-05-20T05:27:55Z

/gemini review

gemini-code-assist

Code Review

This pull request introduces the excerpter package, a tool for synchronizing code excerpts in Markdown documentation with source files. It includes a CLI, extraction and injection logic, and various text transformations. Review feedback identifies a potential path traversal vulnerability in path joining, suggests normalizing paths in the region cache to prevent redundant processing, and recommends replacing a magic number with a named constant.

jonasfj · 2026-05-20T16:46:45Z

+
+To include lines within a code region,
+add a Dart line comment before the first line in the region with
+`#docregion <name>` where `<name>` is your desired name for the region.


@kevmoo please look at dart-lang/dartdoc#4144

Can talk to others and see if we can agree on something.

IMO, it's preferable if this is as simple as possible.

If we want to have substitution, what is the motivation? And are we sure the benefits outweigh the costs of duplicating a few examples.

I can see how a reference using skip=5 could be hard to maintain, how will I when editing the code file that contains the doc-region know that it's referenced somewhere with skip=5 and that this has to be meaningful.

I guess you'll be able to see it in the PR diff (if you read all the diff, but not if you skim it). But for something like {$example path/to/example/code.dart#myregion} a skip=5 option would be dangerous, because when editing path/to/example/code.dart I can see #region myregion but I can't really know that one place the region is used with skip-5 and in another it's not. And with dartdoc API doc changes won't be visible in the PR.

The same concern applies with substituions, etc. this is my main concern: too many features makes updating code examples dangerous, because it hard to know how the docregion is being referenced (and what substitutions it is subject to).

@parlough do you have some context on all the options here?

Do we need them? and is it really wise to have so many options.

FYI @szakarias

I don't have the original context as I just reimplemented the options originally supported and we used, but it's true some of the options are perhaps quite specific to their usage in our docs.

Some of our code snippets are carefully modified to be focused or even incorrect on purpose. As a result, we use replace quite heavily. The other options are mostly there there for working with snippet source files that are perhaps not hand written, don't support inline comments (like JSON), or otherwise shouldn't have the docregion comments. We do use them, but not as much as replace.

kevmoo · 2026-06-02T19:41:10Z

I LOVE the idea that we have ONE TOOL we use everywhere, but that might mean we need to support some edge cases – extra complexity.

@jonasfj - what do you think?

We can certainly "hide" things or make certain advanced features explicitly opt-in to reduce cognitive load?

jonasfj · 2026-06-02T19:47:22Z

I love the idea of a single tool we use widely.

But the problem is that removing features is really hard!

Much better to start with minimal features.

kevmoo · 2026-06-02T19:51:09Z

I love the idea of a single tool we use widely.

But the problem is that removing features is really hard!

Much better to start with minimal features.

We could ship the minimal feature thing for our current package needs.

But @parlough would still need his custom tool for the web site...with a HUGE feature overlap.

Consider that this is a tool. We don't have big stability restrictions around it.

…on APIs - Export `src/extract.dart` in `lib/excerpter.dart` to expose parsing classes. - Implement synchronous extraction `extractRegionSync` in `ExcerptExtractor`. - Implement string-based extraction `extractRegionsFromContent` in `ExcerptExtractor` to decouple parsing from physical filesystem access. - Add unit tests verifying synchronous extraction, path canonicalization caching, and exception cases.

kevmoo · 2026-06-04T00:47:27Z

I went off and added MORE code here. But for a good reason.

So we can't delete much code from the TOOLING in the Flutter repo by integrating excerpter.

We could bring a pile of stuff into excerpter from the snippet tool, but it would double the size.

BUT what we DO GET - we can use the selection logic in excerpter to make the Flutter snippet example management MUCH easier!!

See here:
kevmoo/flutter@f6511f1

jonasfj · 2026-06-08T10:43:09Z

Consider that this is a tool. We don't have big stability restrictions around it.

if you break behavior and the tool is used across ~10-20 repos, documentation examples in those now break in subtle ways.

Granted the changes from the tool would be checked in. So the next person to run the tool, should notice changes.

kevmoo requested a review from a team as a code owner May 20, 2026 03:51

github-actions Bot added the type-infra A repository infrastructure change or enhancement label May 20, 2026

kevmoo mentioned this pull request May 20, 2026

Add 'excerpter' package to the labs repository dart-lang/labs#325

Closed

fix CI

3047ec5

gemini-code-assist Bot reviewed May 20, 2026

View reviewed changes

agent nits

080e41d

kevmoo requested a review from srawlins as a code owner May 20, 2026 04:03

github-actions Bot added the package:markdown label May 20, 2026

gemini-code-assist Bot reviewed May 20, 2026

View reviewed changes

Comment thread pkgs/snippets/lib/src/inject.dart

Comment thread pkgs/snippets/lib/src/inject.dart

Comment thread pkgs/excerpter/README.md Outdated

Comment thread pkgs/excerpter/README.md Outdated

Comment thread pkgs/excerpter/lib/src/extract.dart Outdated

review nits

5d04116

gemini-code-assist Bot reviewed May 20, 2026

View reviewed changes

Comment thread pkgs/snippets/pubspec.yaml

Comment thread pkgs/excerpter/bin/excerpter.dart Outdated

Comment thread pkgs/excerpter/bin/excerpter.dart Outdated

Comment thread pkgs/markdown/tool/update_shared.dart

kevmoo added 2 commits May 19, 2026 21:52

better args logic

bf5fb6c

ignore the error

60781c0

github-actions Bot removed the package:markdown label May 20, 2026

kevmoo added 3 commits May 19, 2026 21:58

less silly w/ our exit codes

28d6f0e

review nits

7620859

code owner cleanup

992be3b

gemini-code-assist Bot reviewed May 20, 2026

View reviewed changes

Comment thread pkgs/excerpter/lib/src/inject.dart Outdated

Comment thread pkgs/snippets/lib/src/extract.dart

Comment thread pkgs/excerpter/lib/src/extract.dart Outdated

kevmoo added 2 commits May 19, 2026 22:49

review nits

4f74d2e

review nits

09ac517

kevmoo added the package:excerpter label May 20, 2026

jonasfj reviewed May 20, 2026

View reviewed changes

kevmoo added 2 commits June 3, 2026 13:49

Merge remote-tracking branch 'origin/HEAD' into excerpter

d637580

Renamed to pkg:snippets

1cff181

kevmoo changed the title ~~Add 'excerpter' package to the tools repository~~ pkg:snippets: new package! Jun 4, 2026

Uh oh!

Conversation

kevmoo commented May 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented May 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Package publishing

Uh oh!

github-actions Bot commented May 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Health

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kevmoo commented May 20, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kevmoo commented May 20, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kevmoo commented May 20, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jonasfj May 20, 2026

Choose a reason for hiding this comment

Uh oh!

jonasfj May 28, 2026

Choose a reason for hiding this comment

Uh oh!

jonasfj Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

parlough Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

kevmoo commented Jun 2, 2026

Uh oh!

jonasfj commented Jun 2, 2026

Uh oh!

kevmoo commented Jun 2, 2026

Uh oh!

kevmoo commented Jun 4, 2026

Uh oh!

jonasfj commented Jun 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

kevmoo commented May 20, 2026 •

edited

Loading

github-actions Bot commented May 20, 2026 •

edited

Loading

github-actions Bot commented May 20, 2026 •

edited

Loading