@shivaedev/quality 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.16.0 - 2026-10-06
+
+### Added
+
+- The README states the story-test convention: a test reads as a story over a domain kit the repository keeps in `test-support/`, names its setup as traits, acts through real entry points and prints the story when it fails.
+- `tests/story-setup` reports, in a test file, a top-level function named `seed…`, `make…`, `build…` or `setup…`, and each call that writes fixture files through Node's `fs` or `fs/promises`, such as `writeFileSync`, `mkdirSync` or `mkdtemp`. Its message asks for the setup as traits of the story kit and points at the convention. Files under `test-support/` are not tests, so the kit itself is not reported. The rule has no fix. A repository that upgrades records its existing findings with `quality baseline write --rule tests/story-setup`.
+
 ## 0.15.0 - 2026-10-05
 
 ### Added

package/README.md

@@ -520,7 +520,34 @@ Both rules take a `suites` option, `.gitignore` patterns of folders that hold te
 
 ### Test code
 
-Test code is a test file, as `tests/follow` reads the name (`*.test.ts` or `*.spec.ts`, with any environment), or any file under a folder named `test-support/`. `test-support/` is the one folder name for the fixtures, harnesses and generated clients that tests share. Test code ships nowhere, so the rules that check shipped code skip it: `imports/fences` never holds it, and `structure/max-lines` gives it the test limit. The test rules still read only test files: a file under `test-support/` is not a test, so `tests/follow` and `tests/colocated` leave it alone.
+Test code is a test file, as `tests/follow` reads the name (`*.test.ts` or `*.spec.ts`, with any environment), or any file under a folder named `test-support/`. `test-support/` is the one folder name for the fixtures, harnesses and generated clients that tests share. Test code ships nowhere, so the rules that check shipped code skip it: `imports/fences` never holds it, and `structure/max-lines` gives it the test limit. The test rules still read only test files: a file under `test-support/` is not a test, so `tests/follow`, `tests/colocated` and `tests/story-setup` leave it alone.
+
+## Story tests
+
+A test reads as a short story over the domain: what exists, what someone does, and what is true afterwards. The words come from a story kit that the repository keeps in `test-support/`, so a test says what it needs in domain words and never builds state by hand.
+
+```ts
+it("ships a paid order from stock", () => {
+	const { customer, warehouse } = newShop(hasInStock(3, "lamp"), hasInCart(1, "lamp"));
+
+	customer.checksOut();
+	warehouse.settles();
+
+	expect(warehouse.shipped()).toEqual(["lamp"]);
+	expect(warehouse.inStock("lamp")).toBe(2);
+});
+```
+
+- **Setup is traits.** A trait is one sentence of setup in domain words and the change it makes, such as `hasInStock(3, "lamp")`. A test hands the traits it needs to the kit's entry point, such as `newShop(...traits)`, and a setup that recurs becomes one named trait made of others. A trait that asks for an impossible state refuses and fails the test, instead of seeding it quietly.
+- **Actions go through real entry points.** The test acts the way a user or caller does: through the command, service, route or UI path they reach, never by writing internal state.
+- **Failures print the story.** Every trait and action adds a line to the story log, and a failing test prints it, so the failure says what happened, not only which values differ.
+
+`tests/story-setup` holds test files to this. In a test file, it reports:
+
+- a top-level function whose name starts with the word `seed`, `make`, `build` or `setup`, declared as a function or as a variable that holds an arrow function or function expression: `function seedCart()`, `const makeRun = () => …`. The prefix is a whole word, so `builder` and `settings` pass;
+- a call that writes fixture files through Node's `fs` or `fs/promises`: `writeFile`, `appendFile`, `mkdir`, `mkdtemp`, `copyFile`, `cp` and `symlink`, each in its sync form too, whether imported by name, through a namespace or default import, or through `promises`.
+
+Each finding names its line and has the helper or the function it calls as its subject. Its message asks for the setup as traits of the story kit in `test-support/` and points here. A file under `test-support/` is not a test, so the kit itself builds state and writes files freely. The rule only reports; nothing rewrites a test. A repository adopts it through the baseline: `quality baseline write --rule tests/story-setup`.
 
 ## Vitest projects
 
@@ -587,4 +614,4 @@ A package that type-checks its tests with one config and builds `src` with anoth
 
 ## Validation
 
-`pnpm ready` checks formatting, TypeScript 7, the rules, the import graph against seeded repositories and the fence policy against its examples, config, discovery, registry, baseline and report behavior, the command line against seeded repositories and git histories, the Biome preset against every rule Biome recommends and against its declarations, its naming rules and plugins against seeded files that break and keep each one, the file, folder, other-file and test naming rules against seeded trees, the `biome` and `manifests/sorted` rules and `quality fix` against seeded repositories, the Vitest projects against a seeded repository that Vitest runs, an installed tarball consumer that type-checks a config and runs the `quality` bin through a baseline that takes in the preset's lint and plugin findings, and installed consumers that extend each tsconfig preset, type-check a fixture with an expected error for each check the base turns on, and run the package preset's build output.
+`pnpm ready` checks formatting, TypeScript 7, the rules, the import graph against seeded repositories and the fence policy against its examples, config, discovery, registry, baseline and report behavior, the command line against seeded repositories and git histories, the Biome preset against every rule Biome recommends and against its declarations, its naming rules and plugins against seeded files that break and keep each one, the file, folder, other-file and test naming rules against seeded trees, `tests/story-setup` against seeded test, source and `test-support/` files, the `biome` and `manifests/sorted` rules and `quality fix` against seeded repositories, the Vitest projects against a seeded repository that Vitest runs, an installed tarball consumer that type-checks a config and runs the `quality` bin through a baseline that takes in the preset's lint and plugin findings, and installed consumers that extend each tsconfig preset, type-check a fixture with an expected error for each check the base turns on, and run the package preset's build output.

package/dist/naming/testName.d.ts

@@ -8,5 +8,6 @@ export interface TestName {
     readonly stem: string;
 }
 export declare function testName(path: string): TestName | undefined;
+export declare function isTestSupport(path: string): boolean;
 export declare function isTestCode(path: string): boolean;
 //# sourceMappingURL=testName.d.ts.map

package/dist/naming/testName.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"testName.d.ts","sourceRoot":"","sources":["../../src/naming/testName.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,YAAY,uCAAwC,CAAC;AAElE,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAExD,MAAM,WAAW,QAAQ;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACtB;AAID,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAQ3D;AAID,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEhD"}
+{"version":3,"file":"testName.d.ts","sourceRoot":"","sources":["../../src/naming/testName.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,YAAY,uCAAwC,CAAC;AAElE,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAExD,MAAM,WAAW,QAAQ;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACtB;AAID,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAQ3D;AAID,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEhD"}

package/dist/naming/testName.js

@@ -11,7 +11,10 @@ export function testName(path) {
     return { extension: groups.extension, folder: posix.dirname(path), kind, modifiers, stem };
 }
 const TEST_SUPPORT = "test-support";
+export function isTestSupport(path) {
+    return posix.dirname(path).split("/").includes(TEST_SUPPORT);
+}
 export function isTestCode(path) {
-    return testName(path) !== undefined || posix.dirname(path).split("/").includes(TEST_SUPPORT);
+    return testName(path) !== undefined || isTestSupport(path);
 }
 //# sourceMappingURL=testName.js.map

package/dist/naming/testName.js.map

@@ -1 +1 @@
-{"version":3,"file":"testName.js","sourceRoot":"","sources":["../../src/naming/testName.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AAElC,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,CAAU,CAAC;AAYlE,MAAM,SAAS,GAAG,gEAAgE,CAAC;AAEnF,MAAM,UAAU,QAAQ,CAAC,IAAY;IACpC,MAAM,MAAM,GAAG,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,EAAE,MAAM,CAAC;IAC5D,MAAM,IAAI,GAAG,MAAM,EAAE,IAAI,CAAC;IAC1B,IAAI,MAAM,EAAE,IAAI,KAAK,SAAS,IAAI,MAAM,CAAC,SAAS,KAAK,SAAS,IAAI,CAAC,IAAI,KAAK,MAAM,IAAI,IAAI,KAAK,MAAM,CAAC,EAAE,CAAC;QAC1G,OAAO,SAAS,CAAC;IAClB,CAAC;IACD,MAAM,CAAC,IAAI,GAAG,EAAE,EAAE,GAAG,SAAS,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACzD,OAAO,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;AAC5F,CAAC;AAED,MAAM,YAAY,GAAG,cAAc,CAAC;AAEpC,MAAM,UAAU,UAAU,CAAC,IAAY;IACtC,OAAO,QAAQ,CAAC,IAAI,CAAC,KAAK,SAAS,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC;AAC9F,CAAC"}
+{"version":3,"file":"testName.js","sourceRoot":"","sources":["../../src/naming/testName.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AAElC,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,CAAU,CAAC;AAYlE,MAAM,SAAS,GAAG,gEAAgE,CAAC;AAEnF,MAAM,UAAU,QAAQ,CAAC,IAAY;IACpC,MAAM,MAAM,GAAG,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,EAAE,MAAM,CAAC;IAC5D,MAAM,IAAI,GAAG,MAAM,EAAE,IAAI,CAAC;IAC1B,IAAI,MAAM,EAAE,IAAI,KAAK,SAAS,IAAI,MAAM,CAAC,SAAS,KAAK,SAAS,IAAI,CAAC,IAAI,KAAK,MAAM,IAAI,IAAI,KAAK,MAAM,CAAC,EAAE,CAAC;QAC1G,OAAO,SAAS,CAAC;IAClB,CAAC;IACD,MAAM,CAAC,IAAI,GAAG,EAAE,EAAE,GAAG,SAAS,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACzD,OAAO,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;AAC5F,CAAC;AAED,MAAM,YAAY,GAAG,cAAc,CAAC;AAEpC,MAAM,UAAU,aAAa,CAAC,IAAY;IACzC,OAAO,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC;AAC9D,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,IAAY;IACtC,OAAO,QAAQ,CAAC,IAAI,CAAC,KAAK,SAAS,IAAI,aAAa,CAAC,IAAI,CAAC,CAAC;AAC5D,CAAC"}

package/dist/rules/built-in.d.ts

@@ -29,5 +29,5 @@ export declare const builtInRules: readonly [import("../rule.ts").Rule<"structur
     readonly suites?: readonly string[];
 }>, import("../rule.ts").Rule<"tests/colocated", {
     readonly suites?: readonly string[];
-}>];
+}>, import("../rule.ts").Rule<"tests/story-setup", undefined>];
 //# sourceMappingURL=built-in.d.ts.map

package/dist/rules/built-in.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"built-in.d.ts","sourceRoot":"","sources":["../../src/rules/built-in.ts"],"names":[],"mappings":"AAyBA,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyBf,CAAC"}
+{"version":3,"file":"built-in.d.ts","sourceRoot":"","sources":["../../src/rules/built-in.ts"],"names":[],"mappings":"AA0BA,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;8DA0Bf,CAAC"}

package/dist/rules/built-in.js

@@ -12,6 +12,7 @@ import { importsAliased } from "#rules/imports/aliased.ts";
 import { importCycles } from "#rules/imports/cycles.ts";
 import { importFences } from "#rules/imports/fences.ts";
 import { importsResolvable } from "#rules/imports/resolvable.ts";
+import { storySetup } from "#rules/stories/setup.ts";
 import { biomeOverrides } from "#rules/suppressions/biome-overrides.ts";
 import { biomeRecommended } from "#rules/suppressions/biomeRecommended.ts";
 import { noDoubleCast } from "#rules/suppressions/no-double-cast.ts";
@@ -47,5 +48,6 @@ export const builtInRules = [
     otherNames,
     testsFollow,
     testsColocated,
+    storySetup,
 ];
 //# sourceMappingURL=built-in.js.map

package/dist/rules/built-in.js.map

@@ -1 +1 @@
-{"version":3,"file":"built-in.js","sourceRoot":"","sources":["../../src/rules/built-in.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAC7D,OAAO,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AACxD,OAAO,EAAE,mBAAmB,EAAE,MAAM,0CAA0C,CAAC;AAC/E,OAAO,EAAE,OAAO,EAAE,MAAM,6BAA6B,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,MAAM,sCAAsC,CAAC;AACvE,OAAO,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AACnE,OAAO,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AACpE,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACjE,OAAO,EAAE,cAAc,EAAE,MAAM,wCAAwC,CAAC;AACxE,OAAO,EAAE,gBAAgB,EAAE,MAAM,yCAAyC,CAAC;AAC3E,OAAO,EAAE,YAAY,EAAE,MAAM,uCAAuC,CAAC;AACrE,OAAO,EAAE,QAAQ,EAAE,MAAM,kCAAkC,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,MAAM,6CAA6C,CAAC;AACnF,OAAO,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAChE,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC1D,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C,MAAM,CAAC,MAAM,YAAY,GAAG;IAC3B,QAAQ;IACR,OAAO;IACP,eAAe;IACf,aAAa;IACb,QAAQ;IACR,MAAM;IACN,mBAAmB;IACnB,UAAU;IACV,QAAQ;IACR,YAAY;IACZ,oBAAoB;IACpB,cAAc;IACd,gBAAgB;IAChB,KAAK;IACL,YAAY;IACZ,YAAY;IACZ,iBAAiB;IACjB,cAAc;IACd,eAAe;IACf,gBAAgB;IAChB,WAAW;IACX,UAAU;IACV,WAAW;IACX,cAAc;CACL,CAAC"}
+{"version":3,"file":"built-in.js","sourceRoot":"","sources":["../../src/rules/built-in.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAC7D,OAAO,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AACxD,OAAO,EAAE,mBAAmB,EAAE,MAAM,0CAA0C,CAAC;AAC/E,OAAO,EAAE,OAAO,EAAE,MAAM,6BAA6B,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,MAAM,sCAAsC,CAAC;AACvE,OAAO,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AACnE,OAAO,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AACpE,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACjE,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,wCAAwC,CAAC;AACxE,OAAO,EAAE,gBAAgB,EAAE,MAAM,yCAAyC,CAAC;AAC3E,OAAO,EAAE,YAAY,EAAE,MAAM,uCAAuC,CAAC;AACrE,OAAO,EAAE,QAAQ,EAAE,MAAM,kCAAkC,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,MAAM,6CAA6C,CAAC;AACnF,OAAO,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAChE,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC1D,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C,MAAM,CAAC,MAAM,YAAY,GAAG;IAC3B,QAAQ;IACR,OAAO;IACP,eAAe;IACf,aAAa;IACb,QAAQ;IACR,MAAM;IACN,mBAAmB;IACnB,UAAU;IACV,QAAQ;IACR,YAAY;IACZ,oBAAoB;IACpB,cAAc;IACd,gBAAgB;IAChB,KAAK;IACL,YAAY;IACZ,YAAY;IACZ,iBAAiB;IACjB,cAAc;IACd,eAAe;IACf,gBAAgB;IAChB,WAAW;IACX,UAAU;IACV,WAAW;IACX,cAAc;IACd,UAAU;CACD,CAAC"}

package/dist/rules/stories/fixtureWrites.d.ts

@@ -0,0 +1,7 @@
+import ts from "typescript";
+export interface FixtureWrite {
+    readonly call: ts.CallExpression;
+    readonly name: string;
+}
+export declare function fixtureWrites(source: ts.SourceFile): readonly FixtureWrite[];
+//# sourceMappingURL=fixtureWrites.d.ts.map

package/dist/rules/stories/fixtureWrites.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixtureWrites.d.ts","sourceRoot":"","sources":["../../../src/rules/stories/fixtureWrites.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,YAAY,CAAC;AAyB5B,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC,cAAc,CAAC;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACtB;AAwDD,wBAAgB,aAAa,CAAC,MAAM,EAAE,EAAE,CAAC,UAAU,GAAG,SAAS,YAAY,EAAE,CAiB5E"}

package/dist/rules/stories/fixtureWrites.js

@@ -0,0 +1,83 @@
+import ts from "typescript";
+const FS_MODULES = new Set(["fs", "fs/promises", "node:fs", "node:fs/promises"]);
+const FIXTURE_WRITES = new Set([
+    "appendFile",
+    "appendFileSync",
+    "copyFile",
+    "copyFileSync",
+    "cp",
+    "cpSync",
+    "mkdir",
+    "mkdirSync",
+    "mkdtemp",
+    "mkdtempSync",
+    "symlink",
+    "symlinkSync",
+    "writeFile",
+    "writeFileSync",
+]);
+function fsImportsOf(source) {
+    return source.statements.flatMap((statement) => ts.isImportDeclaration(statement)
+        && ts.isStringLiteral(statement.moduleSpecifier)
+        && FS_MODULES.has(statement.moduleSpecifier.text)
+        && statement.importClause !== undefined
+        ? [statement.importClause]
+        : []);
+}
+function addBindings(clause, functions, namespaces) {
+    const bindings = clause.namedBindings;
+    for (const local of [clause.name, bindings !== undefined && ts.isNamespaceImport(bindings) ? bindings.name : undefined]) {
+        if (local !== undefined) {
+            namespaces.add(local.text);
+        }
+    }
+    for (const element of bindings !== undefined && ts.isNamedImports(bindings) ? bindings.elements : []) {
+        const imported = (element.propertyName ?? element.name).text;
+        if (imported === "promises") {
+            namespaces.add(element.name.text);
+        }
+        else if (FIXTURE_WRITES.has(imported)) {
+            functions.set(element.name.text, imported);
+        }
+    }
+}
+function fsBindingsOf(source) {
+    const functions = new Map();
+    const namespaces = new Set();
+    for (const clause of fsImportsOf(source)) {
+        addBindings(clause, functions, namespaces);
+    }
+    return { functions, namespaces };
+}
+function isFsNamespace(node, bindings) {
+    return ((ts.isIdentifier(node) && bindings.namespaces.has(node.text))
+        || (ts.isPropertyAccessExpression(node) && node.name.text === "promises" && isFsNamespace(node.expression, bindings)));
+}
+function fixtureWriteOf(callee, bindings) {
+    if (ts.isIdentifier(callee)) {
+        return bindings.functions.get(callee.text);
+    }
+    if (ts.isPropertyAccessExpression(callee) && FIXTURE_WRITES.has(callee.name.text) && isFsNamespace(callee.expression, bindings)) {
+        return callee.name.text;
+    }
+    return undefined;
+}
+export function fixtureWrites(source) {
+    const bindings = fsBindingsOf(source);
+    if (bindings.functions.size === 0 && bindings.namespaces.size === 0) {
+        return [];
+    }
+    const writes = [];
+    function visit(node) {
+        if (ts.isCallExpression(node)) {
+            const name = fixtureWriteOf(node.expression, bindings);
+            if (name !== undefined) {
+                writes.push({ call: node, name });
+            }
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(source);
+    return writes;
+}
+//# sourceMappingURL=fixtureWrites.js.map

package/dist/rules/stories/fixtureWrites.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixtureWrites.js","sourceRoot":"","sources":["../../../src/rules/stories/fixtureWrites.ts"],"names":[],"mappings":"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"}

package/dist/rules/stories/setup.d.ts

@@ -0,0 +1,2 @@
+export declare const storySetup: import("#rule.ts").Rule<"tests/story-setup", undefined>;
+//# sourceMappingURL=setup.d.ts.map

package/dist/rules/stories/setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../../src/rules/stories/setup.ts"],"names":[],"mappings":"AA6DA,eAAO,MAAM,UAAU,yDAKrB,CAAC"}

package/dist/rules/stories/setup.js

@@ -0,0 +1,56 @@
+import ts from "typescript";
+import { isTestSupport, testName } from "#naming/testName.ts";
+import { defineRule } from "#rule.ts";
+import { parse } from "#rules/syntax.ts";
+import { fixtureWrites } from "./fixtureWrites.js";
+const SETUP_HELPER = /^(?:seed|make|build|setup)(?![a-z])/u;
+const STORY_KIT = "Name the setup in domain words as traits of the repository's story kit in test-support/, so the test reads as a story: see https://github.com/ShivaeDev/platform/tree/main/packages/quality#story-tests.";
+function isTestFile(path) {
+    return testName(path) !== undefined && !isTestSupport(path);
+}
+function lineOf(source, node) {
+    return source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1;
+}
+function unwrapped(node) {
+    return ts.isParenthesizedExpression(node) ? unwrapped(node.expression) : node;
+}
+function isFunction(node) {
+    return node !== undefined && (ts.isArrowFunction(unwrapped(node)) || ts.isFunctionExpression(unwrapped(node)));
+}
+function helpersOf(statement) {
+    if (ts.isFunctionDeclaration(statement)) {
+        return statement.name === undefined || statement.body === undefined ? [] : [statement.name];
+    }
+    if (!ts.isVariableStatement(statement)) {
+        return [];
+    }
+    return statement.declarationList.declarations.flatMap((declaration) => ts.isIdentifier(declaration.name) && isFunction(declaration.initializer) ? [declaration.name] : []);
+}
+function storySetupIn(file) {
+    const source = isTestFile(file.path) ? parse(file) : undefined;
+    if (source === undefined) {
+        return [];
+    }
+    const helpers = source.statements
+        .flatMap(helpersOf)
+        .filter((name) => SETUP_HELPER.test(name.text))
+        .map((name) => ({
+        file: file.path,
+        line: lineOf(source, name),
+        message: `Declares the setup helper "${name.text}". ${STORY_KIT}`,
+        subject: name.text,
+    }));
+    const writes = fixtureWrites(source).map(({ call, name }) => ({
+        file: file.path,
+        line: lineOf(source, call),
+        message: `Writes a fixture with ${name}. ${STORY_KIT}`,
+        subject: name,
+    }));
+    return [...helpers, ...writes];
+}
+export const storySetup = defineRule({
+    check: ({ sources }) => sources.flatMap(storySetupIn),
+    description: "A test reads as a story over the domain words of the repository's story kit in test-support/. It names its setup as traits instead of declaring seed, make, build or setup helpers or writing fixture files.",
+    id: "tests/story-setup",
+});
+//# sourceMappingURL=setup.js.map

package/dist/rules/stories/setup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.js","sourceRoot":"","sources":["../../../src/rules/stories/setup.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shivaedev/quality",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Repository quality gate with typed rules, a baseline of existing debt and a registry of reasoned exceptions",
   "homepage": "https://github.com/ShivaeDev/platform/tree/main/packages/quality#readme",
   "bugs": {

package/src/naming/testName.ts

@@ -26,6 +26,10 @@ export function testName(path: string): TestName | undefined {
 
 const TEST_SUPPORT = "test-support";
 
+export function isTestSupport(path: string): boolean {
+	return posix.dirname(path).split("/").includes(TEST_SUPPORT);
+}
+
 export function isTestCode(path: string): boolean {
-	return testName(path) !== undefined || posix.dirname(path).split("/").includes(TEST_SUPPORT);
+	return testName(path) !== undefined || isTestSupport(path);
 }

package/src/rules/built-in.ts

@@ -12,6 +12,7 @@ import { importsAliased } from "#rules/imports/aliased.ts";
 import { importCycles } from "#rules/imports/cycles.ts";
 import { importFences } from "#rules/imports/fences.ts";
 import { importsResolvable } from "#rules/imports/resolvable.ts";
+import { storySetup } from "#rules/stories/setup.ts";
 import { biomeOverrides } from "#rules/suppressions/biome-overrides.ts";
 import { biomeRecommended } from "#rules/suppressions/biomeRecommended.ts";
 import { noDoubleCast } from "#rules/suppressions/no-double-cast.ts";
@@ -48,4 +49,5 @@ export const builtInRules = [
 	otherNames,
 	testsFollow,
 	testsColocated,
+	storySetup,
 ] as const;

package/src/rules/stories/fixtureWrites.ts

@@ -0,0 +1,102 @@
+import ts from "typescript";
+
+const FS_MODULES: ReadonlySet<string> = new Set(["fs", "fs/promises", "node:fs", "node:fs/promises"]);
+const FIXTURE_WRITES: ReadonlySet<string> = new Set([
+	"appendFile",
+	"appendFileSync",
+	"copyFile",
+	"copyFileSync",
+	"cp",
+	"cpSync",
+	"mkdir",
+	"mkdirSync",
+	"mkdtemp",
+	"mkdtempSync",
+	"symlink",
+	"symlinkSync",
+	"writeFile",
+	"writeFileSync",
+]);
+
+interface FsBindings {
+	readonly functions: ReadonlyMap<string, string>;
+	readonly namespaces: ReadonlySet<string>;
+}
+
+export interface FixtureWrite {
+	readonly call: ts.CallExpression;
+	readonly name: string;
+}
+
+function fsImportsOf(source: ts.SourceFile): readonly ts.ImportClause[] {
+	return source.statements.flatMap((statement) =>
+		ts.isImportDeclaration(statement)
+		&& ts.isStringLiteral(statement.moduleSpecifier)
+		&& FS_MODULES.has(statement.moduleSpecifier.text)
+		&& statement.importClause !== undefined
+			? [statement.importClause]
+			: [],
+	);
+}
+
+function addBindings(clause: ts.ImportClause, functions: Map<string, string>, namespaces: Set<string>): void {
+	const bindings = clause.namedBindings;
+	for (const local of [clause.name, bindings !== undefined && ts.isNamespaceImport(bindings) ? bindings.name : undefined]) {
+		if (local !== undefined) {
+			namespaces.add(local.text);
+		}
+	}
+	for (const element of bindings !== undefined && ts.isNamedImports(bindings) ? bindings.elements : []) {
+		const imported = (element.propertyName ?? element.name).text;
+		if (imported === "promises") {
+			namespaces.add(element.name.text);
+		} else if (FIXTURE_WRITES.has(imported)) {
+			functions.set(element.name.text, imported);
+		}
+	}
+}
+
+function fsBindingsOf(source: ts.SourceFile): FsBindings {
+	const functions = new Map<string, string>();
+	const namespaces = new Set<string>();
+	for (const clause of fsImportsOf(source)) {
+		addBindings(clause, functions, namespaces);
+	}
+	return { functions, namespaces };
+}
+
+function isFsNamespace(node: ts.Expression, bindings: FsBindings): boolean {
+	return (
+		(ts.isIdentifier(node) && bindings.namespaces.has(node.text))
+		|| (ts.isPropertyAccessExpression(node) && node.name.text === "promises" && isFsNamespace(node.expression, bindings))
+	);
+}
+
+function fixtureWriteOf(callee: ts.Expression, bindings: FsBindings): string | undefined {
+	if (ts.isIdentifier(callee)) {
+		return bindings.functions.get(callee.text);
+	}
+	if (ts.isPropertyAccessExpression(callee) && FIXTURE_WRITES.has(callee.name.text) && isFsNamespace(callee.expression, bindings)) {
+		return callee.name.text;
+	}
+	return undefined;
+}
+
+export function fixtureWrites(source: ts.SourceFile): readonly FixtureWrite[] {
+	const bindings = fsBindingsOf(source);
+	if (bindings.functions.size === 0 && bindings.namespaces.size === 0) {
+		return [];
+	}
+	const writes: FixtureWrite[] = [];
+	function visit(node: ts.Node): void {
+		if (ts.isCallExpression(node)) {
+			const name = fixtureWriteOf(node.expression, bindings);
+			if (name !== undefined) {
+				writes.push({ call: node, name });
+			}
+		}
+		ts.forEachChild(node, visit);
+	}
+	visit(source);
+	return writes;
+}

package/src/rules/stories/setup.ts

@@ -0,0 +1,67 @@
+import ts from "typescript";
+import { isTestSupport, testName } from "#naming/testName.ts";
+import { defineRule, type Finding, type SourceFile } from "#rule.ts";
+import { parse } from "#rules/syntax.ts";
+import { fixtureWrites } from "./fixtureWrites.ts";
+
+const SETUP_HELPER = /^(?:seed|make|build|setup)(?![a-z])/u;
+const STORY_KIT =
+	"Name the setup in domain words as traits of the repository's story kit in test-support/, so the test reads as a story: see https://github.com/ShivaeDev/platform/tree/main/packages/quality#story-tests.";
+
+function isTestFile(path: string): boolean {
+	return testName(path) !== undefined && !isTestSupport(path);
+}
+
+function lineOf(source: ts.SourceFile, node: ts.Node): number {
+	return source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1;
+}
+
+function unwrapped(node: ts.Expression): ts.Expression {
+	return ts.isParenthesizedExpression(node) ? unwrapped(node.expression) : node;
+}
+
+function isFunction(node: ts.Expression | undefined): boolean {
+	return node !== undefined && (ts.isArrowFunction(unwrapped(node)) || ts.isFunctionExpression(unwrapped(node)));
+}
+
+function helpersOf(statement: ts.Statement): readonly ts.Identifier[] {
+	if (ts.isFunctionDeclaration(statement)) {
+		return statement.name === undefined || statement.body === undefined ? [] : [statement.name];
+	}
+	if (!ts.isVariableStatement(statement)) {
+		return [];
+	}
+	return statement.declarationList.declarations.flatMap((declaration) =>
+		ts.isIdentifier(declaration.name) && isFunction(declaration.initializer) ? [declaration.name] : [],
+	);
+}
+
+function storySetupIn(file: SourceFile): readonly Finding[] {
+	const source = isTestFile(file.path) ? parse(file) : undefined;
+	if (source === undefined) {
+		return [];
+	}
+	const helpers = source.statements
+		.flatMap(helpersOf)
+		.filter((name) => SETUP_HELPER.test(name.text))
+		.map((name) => ({
+			file: file.path,
+			line: lineOf(source, name),
+			message: `Declares the setup helper "${name.text}". ${STORY_KIT}`,
+			subject: name.text,
+		}));
+	const writes = fixtureWrites(source).map(({ call, name }) => ({
+		file: file.path,
+		line: lineOf(source, call),
+		message: `Writes a fixture with ${name}. ${STORY_KIT}`,
+		subject: name,
+	}));
+	return [...helpers, ...writes];
+}
+
+export const storySetup = defineRule({
+	check: ({ sources }) => sources.flatMap(storySetupIn),
+	description:
+		"A test reads as a story over the domain words of the repository's story kit in test-support/. It names its setup as traits instead of declaring seed, make, build or setup helpers or writing fixture files.",
+	id: "tests/story-setup",
+});