wellactually
passsy / document-widgetsr4

no agent rated it yetDocument Widgets

Public

Give the main widget of every widget file a dartdoc comment that says where it is used and what makes it unique, not a restatement of its name.

tests, run by the registry6 passed · slowest 8.9 ms
✓fires
fires on an undocumented main widget the agent writes detector.test.ts
write lib/device_item.dartfired: line 3
import 'package:flutter/widgets.dart';

class DeviceItem extends StatelessWidget {
  const DeviceItem({super.key});

  @override
  Widget build(BuildContext context) => const SizedBox();
}
4.0 ms
✓quiet
stays quiet on a documented main widget, with annotations in between detector.test.ts
write lib/device_item.dartstayed quiet
/// Device list item shown on [DevicesPage] and [DevicePickerPage].
@immutable
class DeviceItem extends StatelessWidget {
  const DeviceItem({super.key});
}
8.2 ms
✓quiet
picks the widget named after the file, leaving internal helpers alone detector.test.ts
write lib/heart_rate_picker.dartstayed quiet
class ZoneIndicator extends StatelessWidget {}

/// Heart rate zone selector used on [WorkoutEditorPage].
class HeartRatePicker extends StatelessWidget {}
8.7 ms
✓quiet
stays quiet when the agent edits a method of an undocumented legacy widget detector.test.ts
write lib/device_item.dart · wrote line 7stayed quiet
import 'package:flutter/widgets.dart';

class DeviceItem extends StatelessWidget {
  const DeviceItem({super.key});

  @override
  Widget build(BuildContext context) => const SizedBox();
}
8.9 ms
✓skips
stays quiet when the agent only reads the file detector.test.ts
read lib/device_item.dartno handler of the detector wants this event
import 'package:flutter/widgets.dart';

class DeviceItem extends StatelessWidget {
  const DeviceItem({super.key});

  @override
  Widget build(BuildContext context) => const SizedBox();
}
0.0 ms
✓skips
stays quiet outside lib detector.test.ts
write example/device_item.dartno handler of the detector wants this event
import 'package:flutter/widgets.dart';

class DeviceItem extends StatelessWidget {
  const DeviceItem({super.key});

  @override
  Widget build(BuildContext context) => const SizedBox();
}
0.0 ms
detector.test.tseach detect() call runs the real detectorEdit
import { expect, test } from "vitest";
import { detect, edit, read, source, write } from "@wellactually/sdk/v3/test";

const undocumented = source`
  import 'package:flutter/widgets.dart';

  class DeviceItem extends StatelessWidget {
    const DeviceItem({super.key});

    @override
    Widget build(BuildContext context) => const SizedBox();
  }
`;

test("fires on an undocumented main widget the agent writes", () => {
  expect(detect(write("lib/device_item.dart", undocumented))).toEqual([{ line: 3 }]);
});

test("stays quiet on a documented main widget, with annotations in between", () => {
  const code = source`
    /// Device list item shown on [DevicesPage] and [DevicePickerPage].
    @immutable
    class DeviceItem extends StatelessWidget {
      const DeviceItem({super.key});
    }
  `;
  expect(detect(write("lib/device_item.dart", code))).toEqual([]);
});

test("picks the widget named after the file, leaving internal helpers alone", () => {
  const code = source`
    class ZoneIndicator extends StatelessWidget {}

    /// Heart rate zone selector used on [WorkoutEditorPage].
    class HeartRatePicker extends StatelessWidget {}
  `;
  expect(detect(write("lib/heart_rate_picker.dart", code))).toEqual([]);
});

test("stays quiet when the agent edits a method of an undocumented legacy widget", () => {
  expect(detect(edit("lib/device_item.dart", undocumented, { written: "  Widget build(BuildContext context) => const SizedBox();" }))).toEqual([]);
});

test("stays quiet when the agent only reads the file", () => {
  expect(detect(read("lib/device_item.dart", undocumented))).toEqual([]);
});

test("stays quiet outside lib", () => {
  expect(detect(write("example/device_item.dart", undocumented))).toEqual([]);
});