declapract-typescript-ehmpathy 0.49.12 → 0.49.14

package/dist/practices/lint/best-practice/.depcheckrc.yml.declapract.ts

@@ -1,42 +1,174 @@
 // eslint-disable-next-line import/no-extraneous-dependencies
-import { FileCheckType, type FileFixFunction } from 'declapract';
+import type {
+  FileCheckFunction,
+  FileContentsFunction,
+  FileFixFunction,
+} from 'declapract';
+import { readFile } from 'fs/promises';
+import { ConstraintError, MalfunctionError } from 'helpful-errors';
 // eslint-disable-next-line import/no-extraneous-dependencies
 import yaml from 'yaml';
 
-export const check = FileCheckType.CONTAINS;
+import path from 'node:path';
+import { isJsonObject } from '../../../utils/asJsonMergedDeep';
 
-export const fix: FileFixFunction = (contents, context) => {
-  if (!contents) return { contents: context.declaredFileContents };
+/**
+ * .what = the seq keys of `.depcheckrc.yml` this practice declares and merges
+ * .why  = each is a list of entries a repo may extend with its own; the practice only
+ *         guarantees the presence of its declared entries, never their order or exclusivity
+ */
+const MERGED_SEQ_KEYS = ['ignores', 'ignorePatterns'] as const;
+type MergedSeqKey = (typeof MERGED_SEQ_KEYS)[number];
 
-  const declaredContents = context.declaredFileContents ?? '';
+/**
+ * .what = the ignores an expo repo adds atop the base list
+ * .why  = expo owns the bundled metro, so a consumer pins no `metro-config`; a require of it
+ *         from `metro.config.js` reads to depcheck as an undeclared dep (#609). a union, so a
+ *         narrow `--practice lint` apply (where the expo signal goes dark) strips no line
+ */
+const IGNORES_EXPO = ['metro-config'];
 
-  // Parse both files as YAML (using parseDocument to preserve comments)
-  const currentDoc = yaml.parseDocument(contents);
-  const declaredParsed = yaml.parse(declaredContents) as { ignores?: string[] };
+/**
+ * .what = reads the declared seq entries for a key from a parsed `.depcheckrc.yml`
+ * .why  = one shape for check + fix, so the gate and the repair agree
+ */
+const getSeqEntries = (input: {
+  parsed: unknown;
+  key: MergedSeqKey;
+}): string[] => {
+  const value = isJsonObject(input.parsed)
+    ? input.parsed[input.key]
+    : undefined;
+  return Array.isArray(value)
+    ? value.filter((entry): entry is string => typeof entry === 'string')
+    : [];
+};
+
+/**
+ * .what = the seq node a `.depcheckrc.yml` key holds; halts loud where the key holds no list
+ * .why  = an entry can only be added to a list; a scalar or map under the key is a file the merge
+ *         cannot repair, so it names the key rather than throw a bare TypeError on `.add`
+ */
+const asSeqNode = (input: { node: unknown; key: string }): yaml.YAMLSeq => {
+  if (!yaml.isSeq(input.node))
+    throw new ConstraintError(
+      `.depcheckrc.yml \`${input.key}\` is not a list`,
+      {
+        key: input.key,
+        hint: `make \`${input.key}\` a yaml list, then run \`declapract apply\` again`,
+      },
+    );
+  return input.node;
+};
+
+/**
+ * .what = the parsed declared `.depcheckrc.yml`; halts loud when declapract emitted none
+ * .why  = an absent declared side parses to no entries, which would let the check approve any
+ *         file; a declared template is always emitted for this best-practice, so its absence is a
+ *         malfunction to name, never a silent pass
+ */
+const asDeclaredParsed = (input: {
+  declaredFileContents: string | null;
+  relativeFilePath: string;
+}): unknown => {
+  if (input.declaredFileContents === null)
+    throw new MalfunctionError(
+      'the lint practice emitted no declared .depcheckrc.yml',
+      { relativeFilePath: input.relativeFilePath },
+    );
+  return yaml.parse(input.declaredFileContents);
+};
 
-  const currentIgnores =
-    (currentDoc.toJSON() as { ignores?: string[] })?.ignores ?? [];
-  const declaredIgnores = declaredParsed?.ignores ?? [];
+/**
+ * .what = the declared `.depcheckrc.yml`, usecase-aware for the expo runtime
+ * .why  = an expo repo needs `metro-config` ignored; every other repo gets the base template
+ */
+export const contents: FileContentsFunction = async (context) => {
+  const base = await readFile(path.join(__dirname, '.depcheckrc.yml'), 'utf-8');
+  if (!context.projectPractices.includes('tests-expo')) return base;
+
+  // union the expo ignores into the base, comments kept
+  const doc = yaml.parseDocument(base);
+  const ignoresNode = asSeqNode({ node: doc.get('ignores'), key: 'ignores' });
+  IGNORES_EXPO.forEach((ignore) => ignoresNode.add(ignore)); // .note = deliberate mutation — yaml doc api
+  return doc.toString();
+};
 
-  // Find missing ignores
-  const missingIgnores = declaredIgnores.filter(
-    (item) => !currentIgnores.includes(item),
+/**
+ * .what = the declared entries of one seq key that the found file lacks
+ */
+const getAllEntriesAbsent = (input: {
+  declared: unknown;
+  found: unknown;
+  key: MergedSeqKey;
+}): string[] => {
+  const entriesFound = getSeqEntries({ parsed: input.found, key: input.key });
+  return getSeqEntries({ parsed: input.declared, key: input.key }).filter(
+    (entry) => !entriesFound.includes(entry),
   );
+};
+
+/**
+ * .what = throws when a declared `ignores` or `ignorePatterns` entry is absent
+ * .why  = a findsert gate: the repo may hold its own entries in any order, so the check
+ *         mandates the PRESENCE of each declared entry, never textual equality — which
+ *         also makes `check(fix(x))` pass (a plain-text CONTAINS never could, once a repo
+ *         holds its own entries)
+ * .note = best-practice semantics: throw = violated, return = followed
+ */
+export const check: FileCheckFunction = (contents, context) => {
+  if (!contents)
+    throw new ConstraintError('.depcheckrc.yml is absent', {
+      relativeFilePath: context.relativeFilePath,
+    });
+  const found = yaml.parse(contents);
+  const declared = asDeclaredParsed(context);
+  const absent = MERGED_SEQ_KEYS.flatMap((key) =>
+    getAllEntriesAbsent({ declared, found, key }).map(
+      (entry) => `${key}: ${entry}`,
+    ),
+  );
+  if (absent.length)
+    throw new ConstraintError(
+      '.depcheckrc.yml lacks declared entries; run `declapract apply` to merge them',
+      { absent },
+    );
+};
+
+/**
+ * .what = merges each declared `ignores` + `ignorePatterns` entry into the extant file
+ * .why  = a CONTAINS template alone never reaches an extant file (#639); the merge seeds a
+ *         seq if absent, adds each absent entry, and keeps the repo's own entries + comments
+ * .note = a fixed point: a present entry is never added twice, so fix(fix(x)) === fix(x)
+ */
+export const fix: FileFixFunction = (contents, context) => {
+  if (!contents) return { contents: context.declaredFileContents };
+
+  // parse both files (parseDocument keeps comments)
+  const currentDoc = yaml.parseDocument(contents);
+  const currentParsed = currentDoc.toJSON();
+  const declaredParsed = asDeclaredParsed(context);
 
-  if (missingIgnores.length === 0) return { contents };
+  // merge each seq key
+  const changed = MERGED_SEQ_KEYS.map((key) => {
+    const absentEntries = getAllEntriesAbsent({
+      declared: declaredParsed,
+      found: currentParsed,
+      key,
+    });
+    if (!absentEntries.length) return false;
 
-  // get the ignores seq node, seeding an empty seq onto the doc if absent
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  const ignoresNode = ((): any => {
-    const node = currentDoc.get('ignores');
-    if (node) return node;
-    currentDoc.set('ignores', []);
-    return currentDoc.get('ignores');
-  })();
+    // get the seq node; seed an empty seq onto the doc if absent
+    if (!currentDoc.get(key)) currentDoc.set(key, currentDoc.createNode([]));
+    const seqNode = asSeqNode({ node: currentDoc.get(key), key });
 
-  // .note = deliberate mutation — the yaml document api mutates the seq node in
-  // place to preserve the surrounding comments; there is no immutable seq-add
-  missingIgnores.forEach((ignore) => ignoresNode.add(ignore));
+    // add each absent declared entry to the repo's own list
+    // .note = deliberate mutation — the yaml document api mutates the seq node in
+    // place to keep the comments around it; there is no immutable seq-add
+    absentEntries.forEach((entry) => seqNode.add(entry));
+    return true;
+  });
 
+  if (!changed.some(Boolean)) return { contents };
   return { contents: currentDoc.toString() };
 };

package/dist/practices/lint/best-practice/.dpdmrc.yaml

@@ -4,10 +4,14 @@
 # the org policy `rule.forbid.dpdm-exclude-change`: we check dependencies too, because a prod-dep
 # cycle ships to consumers.
 #
-# with --transform, type imports are erased before analysis and test files drop via the
-# '!(*.test).ts' glob, so an exclude is rarely needed even for a devDep. a devDep may be added as
-# an escape hatch; a prod dep must not, since that ships cycles.
+# when an entry is allowed:
+# - a type-only cycle: never. --transform erases type imports before analysis, so none is owed
+# - a test file: never. the '!(*.test).ts' glob already drops test files
+# - a require cycle inside a third-party devDependency: allowed, one entry per package, each with
+#   a comment that cites the cycle and the upstream issue
+# - a require cycle inside a prod dependency: never. it ships to consumers — dispatch the fix
+#   upstream or replace the dependency
 #
-# the empty list is the policy — an entry of `node_modules` (or dpdm's own `/node_modules/`
-# default) disables the check across every consumer repo.
+# an entry of `node_modules` (or dpdm's own `/node_modules/` default) disables the check across
+# every consumer repo, and the declapract check rejects it.
 exclude: []

package/dist/practices/lint/best-practice/.dpdmrc.yaml.declapract.ts

@@ -0,0 +1,82 @@
+// eslint-disable-next-line import/no-extraneous-dependencies
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+import { ConstraintError } from 'helpful-errors';
+// eslint-disable-next-line import/no-extraneous-dependencies
+import yaml from 'yaml';
+
+/**
+ * .what = whether one exclude entry would hide node_modules from dpdm
+ * .why  = node_modules in scope IS the policy (`rule.forbid.dpdm-exclude-change`); an entry that
+ *         names it disables the cycle check across the whole dependency tree
+ */
+const isNodeModulesEntry = (input: { entry: unknown }): boolean =>
+  String(input.entry).includes('node_modules');
+
+/**
+ * .what = the `.dpdmrc.yaml` policy holds: `exclude` is a list, and no entry names node_modules
+ * .why  = the file was EQUALS, so every apply deleted the cited devDep entries the policy itself
+ *         allows (#628). this check passes any policy-valid list, so an adopter's entry survives.
+ * .note = best-practice semantics: throw = violated, return = followed
+ */
+export const check: FileCheckFunction = (contents, context) => {
+  if (!contents)
+    throw new ConstraintError('.dpdmrc.yaml is absent', {
+      relativeFilePath: context.relativeFilePath,
+    });
+  const exclude: unknown = yaml.parse(contents)?.exclude;
+  if (!Array.isArray(exclude))
+    throw new ConstraintError('.dpdmrc.yaml `exclude` is not a list', {
+      exclude,
+    });
+  const offenders = exclude.filter((entry) => isNodeModulesEntry({ entry }));
+  if (offenders.length)
+    throw new ConstraintError(
+      '.dpdmrc.yaml `exclude` names node_modules, which disables the cycle check on dependencies',
+      { offenders },
+    );
+};
+
+/**
+ * .what = write the declared file when absent; otherwise repair only the policy breach
+ * .why  = a check with no usable fix makes declapract mark the whole file manual (#607), so the
+ *         fix must turn every red the check can raise into green: it seeds `exclude: []` when the
+ *         key is absent or not a list, and drops only the node_modules entries. the adopter's other
+ *         entries and comments survive.
+ * .note = a fixed point: on a policy-valid file it returns the contents unchanged
+ */
+export const fix: FileFixFunction = (contents, context) => {
+  if (!contents) return { contents: context.declaredFileContents };
+
+  // parse with comments kept
+  const doc = yaml.parseDocument(contents);
+
+  // a root that does not parse, or is not a map, holds no policy to keep; write the declared file
+  if (doc.errors.length || (doc.contents !== null && !yaml.isMap(doc.contents)))
+    return { contents: context.declaredFileContents };
+  const exclude: unknown = doc.toJSON()?.exclude;
+
+  // seed an empty list when the key is absent or not a list
+  if (!Array.isArray(exclude)) {
+    doc.set('exclude', doc.createNode([]));
+    return { contents: doc.toString() };
+  }
+
+  // drop only the node_modules entries from the repo's own list, judged by each item's resolved value (an alias or a
+  // non-scalar resolves exactly as the check reads it), aligned to the seq by index
+  if (!exclude.some((entry) => isNodeModulesEntry({ entry })))
+    return { contents };
+  const seq = doc.get('exclude');
+
+  // an alias to a list holds no items in place; set the kept values as a fresh list
+  if (!yaml.isSeq(seq)) {
+    doc.set(
+      'exclude',
+      doc.createNode(exclude.filter((entry) => !isNodeModulesEntry({ entry }))),
+    );
+    return { contents: doc.toString() };
+  }
+  seq.items = seq.items.filter(
+    (_item, index) => !isNodeModulesEntry({ entry: exclude[index] }),
+  ); // .note = deliberate mutation — the yaml document api keeps comments only in place
+  return { contents: doc.toString() };
+};

package/dist/practices/lint/best-practice/biome.jsonc

@@ -9,6 +9,7 @@
     "includes": [
       "**/src/**/*.ts",
       "**/provision/**/*.ts",
+      "**/blackbox/**/*.ts",
       "!**/dist",
       "!**/coverage",
       "!**/node_modules",
@@ -39,16 +40,9 @@
             "groups": [
               ":SIDE_EFFECT:",
               ":BLANK_LINE:",
-              [
-                ":PACKAGE:",
-                "!@src",
-                "!@src/**"
-              ],
+              [":PACKAGE:", "!@src", "!@src/**"],
               ":BLANK_LINE:",
-              [
-                "@src",
-                "@src/**"
-              ],
+              ["@src", "@src/**"],
               ":BLANK_LINE:",
               ":RELATIVE:"
             ]
@@ -83,7 +77,15 @@
           "fix": "none"
         },
         "useImportType": "error",
-        "noParameterAssign": "off"
+        "noParameterAssign": "off",
+        "noRestrictedImports": {
+          "level": "error",
+          "options": {
+            "paths": {
+              "simple-lambda-testing-methods": "use runLambdaEndpoint from sdk-aws-lambda — .onReferenced in integration tests, .onSerialized in acceptance tests"
+            }
+          }
+        }
       },
       "suspicious": {
         "noExplicitAny": "warn",
@@ -92,7 +94,8 @@
         "noUnsafeDeclarationMerging": "off",
         "useIterableCallbackReturn": "warn",
         "noDuplicateTestHooks": "off",
-        "noThenProperty": "warn"
+        "noThenProperty": "warn",
+        "noFocusedTests": "error"
       },
       "nursery": {
         "noFloatingPromises": "error",

package/dist/practices/lint/best-practice/package.json

@@ -2,7 +2,8 @@
   "devDependencies": {
     "depcheck": "1.4.3",
     "dpdm": "4.0.1",
-    "@biomejs/biome": "2.3.8"
+    "@biomejs/biome": "2.3.8",
+    "yaml": "2.9.1"
   },
   "scripts": {
     "fix:format:biome": "biome check --write",
@@ -10,8 +11,8 @@
     "test:format:biome": "biome format",
     "test:lint:biome": "biome check --diagnostic-level=error",
     "test:lint:biome:all": "biome check",
-    "test:lint:cycles": "dpdm --no-warning --no-tree --transform --exit-code circular:1 --exclude \"$(yq -r '.exclude | join(\"|\") // \"^$\"' .dpdmrc.yaml)\" 'src/**/!(*.test).ts'",
-    "test:lint:deps": "npx depcheck -c ./.depcheckrc.yml",
+    "test:lint:cycles": "EXCL=$(node -p \"(require('yaml').parse(require('fs').readFileSync('.dpdmrc.yaml','utf8'))?.exclude ?? []).join('|')\") && dpdm --no-warning --no-tree --transform --exit-code circular:1 --exclude \"$EXCL\" 'src/**/!(*.test).ts'",
+    "test:lint:deps": "depcheck -c ./.depcheckrc.yml",
     "test:lint": "npm run test:lint:biome && npm run test:lint:cycles && npm run test:lint:deps"
   }
 }

package/dist/practices/lint/biome.jsonc.declapract.integration.test.ts

@@ -0,0 +1,148 @@
+import { spawnSync } from 'node:child_process';
+import { copyFileSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { genTempDir, given, then, useBeforeAll, when } from 'test-fns';
+
+/**
+ * .what = clamps #649 + #666: the shipped biome.jsonc fails lint on a focused test, lints the
+ *         `blackbox/` tree, and bans an import of the retired lambda caller.
+ * .why  = biome's recommended set holds `noFocusedTests` at warn, so a stray `.only` merged clean
+ *         and silently skipped its siblings (#649). and `files.includes` named only `src/` and
+ *         `provision/`, so no rule reached the acceptance suite under `blackbox/` — a ban on
+ *         `simple-lambda-testing-methods` there would have caught naught (#666).
+ * .teeth = each case runs the REAL biome binary over a fixture repo that holds the shipped
+ *          template. drop `noFocusedTests: error`, the `**\/blackbox/**\/*.ts` include, or the
+ *          `noRestrictedImports` path, and the matched case goes green where it must go red.
+ * .note = this file sits at the practice ROOT, so declapract never emits it.
+ */
+
+// the biome binary this repo pins; the fixture lints with the same version adopters run
+const BIOME_BIN = join(process.cwd(), 'node_modules/.bin/biome');
+
+/**
+ * .what = run `biome lint` over the fixture with the shipped template as its config
+ * .why  = the vcs block needs a git root, which a temp dir lacks; the flag turns it off so the
+ *         run reads the config's `files.includes` alone
+ */
+const runBiomeLint = (input: { cwd: string }) => {
+  const result = spawnSync(
+    BIOME_BIN,
+    ['lint', '--vcs-enabled=false', '--max-diagnostics=50', '.'],
+    { cwd: input.cwd, encoding: 'utf8' },
+  );
+  return {
+    status: result.status,
+    output: `${result.stdout}\n${result.stderr}`,
+  };
+};
+
+/**
+ * .what = write a fixture repo: the shipped biome.jsonc plus one source file
+ * .why  = each case owns its own dir, so no case's file can leak into another's lint run
+ */
+const genFixtureRepo = (input: {
+  root: string;
+  slug: string;
+  file: { path: string; lines: string[] };
+}): string => {
+  const dir = join(input.root, input.slug);
+  const filePath = join(dir, input.file.path);
+  mkdirSync(join(filePath, '..'), { recursive: true });
+  copyFileSync(
+    join(__dirname, 'best-practice/biome.jsonc'),
+    join(dir, 'biome.jsonc'),
+  );
+  writeFileSync(filePath, input.file.lines.join('\n'));
+  return dir;
+};
+
+describe('lint biome.jsonc', () => {
+  given('[case1] a repo with the shipped biome.jsonc', () => {
+    const tempDir = genTempDir({ slug: 'lint-biome-jsonc' });
+
+    when('[t0] a src test holds an it.only', () => {
+      const result = useBeforeAll(async () =>
+        runBiomeLint({
+          cwd: genFixtureRepo({
+            root: tempDir,
+            slug: 't0',
+            file: {
+              path: 'src/getSurfReport.test.ts',
+              lines: [
+                "describe('getSurfReport', () => {",
+                "  it.only('reads the swell', () => {",
+                '    expect(1).toEqual(1);',
+                '  });',
+                '});',
+                '',
+              ],
+            },
+          }),
+        }),
+      );
+
+      then('lint fails at lint/suspicious/noFocusedTests', () => {
+        expect(result.output).toContain('lint/suspicious/noFocusedTests');
+        expect(result.status).not.toEqual(0);
+      });
+    });
+
+    when('[t1] a blackbox test imports simple-lambda-testing-methods', () => {
+      const result = useBeforeAll(async () =>
+        runBiomeLint({
+          cwd: genFixtureRepo({
+            root: tempDir,
+            slug: 't1',
+            file: {
+              path: 'blackbox/lambdas/getSurfReport.acceptance.test.ts',
+              lines: [
+                "import { invokeLambdaForTesting } from 'simple-lambda-testing-methods';",
+                '',
+                'export const invoke = invokeLambdaForTesting;',
+                '',
+              ],
+            },
+          }),
+        }),
+      );
+
+      then('lint reaches blackbox/ and fails at noRestrictedImports', () => {
+        expect(result.output).toContain('lint/style/noRestrictedImports');
+        expect(result.output).toContain(
+          'blackbox/lambdas/getSurfReport.acceptance.test.ts',
+        );
+        expect(result.status).not.toEqual(0);
+      });
+
+      then('the message names the replacement', () => {
+        expect(result.output).toContain('runLambdaEndpoint');
+      });
+    });
+
+    when('[t2] a blackbox test imports from sdk-aws-lambda', () => {
+      const result = useBeforeAll(async () =>
+        runBiomeLint({
+          cwd: genFixtureRepo({
+            root: tempDir,
+            slug: 't2',
+            file: {
+              path: 'blackbox/lambdas/getSurfReport.acceptance.test.ts',
+              lines: [
+                "import { runLambdaEndpoint } from 'sdk-aws-lambda';",
+                '',
+                'export const run = runLambdaEndpoint;',
+                '',
+              ],
+            },
+          }),
+        }),
+      );
+
+      then('lint passes', () => {
+        expect(result.output).not.toContain('noRestrictedImports');
+        expect(result.status).toEqual(0);
+      });
+    });
+  });
+});

package/dist/practices/lint/depcheck-denylisted-ignores.declapract.integration.test.ts

@@ -0,0 +1,112 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { executeApply } from 'declapract';
+import { genTempDir, given, then, useBeforeAll, useThen, when } from 'test-fns';
+import yaml from 'yaml';
+
+import { check as checkOfDenylist } from './bad-practices/depcheck-denylisted-ignores/.depcheckrc.yml.declapract';
+
+// executeApply evaluates the whole lint practice before the `file` filter narrows it
+jest.setTimeout(5 * 60 * 1000);
+
+const DENYLISTED_IN_FIXTURE = ['date-fns', 'ts-node', 'core-js'];
+
+/**
+ * .what = proves the depcheck-denylisted-ignores bad practice through the real pipeline
+ * .why  = the unit suite proves the fix in isolation; only executeApply proves the bad-practice
+ *         path matches the repo-root `.depcheckrc.yml`, the check gates the fix, the removal
+ *         composes with the best-practice merge on the same file, and a rerun settles
+ *         (rule.require.declapract-integration-tests, rule.require.idempotent-fixes)
+ * .note = this file sits at the practice ROOT, never directly under `bad-practices/`, where
+ *         declapract would fail to extract a bad-practice name
+ * .note = each `{} as any` context is a documented cast (rule.forbid.as-cast): this check reads
+ *         only its contents, never a context field. removal path: a declapract partial-context builder
+ */
+describe('lint depcheck-denylisted-ignores', () => {
+  given('[case1] a node repo whose .depcheckrc.yml ignores denylisted packages', () => {
+    const tempDir = genTempDir({
+      slug: 'lint-depcheckrc-denylisted',
+      clone: './src/practices/lint/.test/assets/repo-depcheckrc-denylisted',
+      symlink: [{ at: 'declarations', to: './src/.test/assets/lint/declarations' }],
+    });
+    const read = () =>
+      fs.readFile(path.join(tempDir, '.depcheckrc.yml'), 'utf-8');
+    const apply = () =>
+      executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        file: '.depcheckrc.yml',
+      });
+
+    when('[t0] before any apply', () => {
+      then('the bad practice is detected on the input', async () => {
+        expect(() => checkOfDenylist(null, {} as any)).toThrow();
+        const before = await read();
+        expect(() => checkOfDenylist(before, {} as any)).not.toThrow();
+      });
+
+      then('the input file matches snapshot', async () => {
+        expect(await read()).toMatchSnapshot('.depcheckrc.yml — before');
+      });
+    });
+
+    when('[t1] apply runs', () => {
+      const scene = useThen('apply settles', async () => {
+        await apply();
+        const after = await read();
+        const parsed = yaml.parse(after) as {
+          ignores: string[];
+          ignorePatterns: string[];
+        };
+        return { after, ignores: parsed.ignores, ignorePatterns: parsed.ignorePatterns };
+      });
+
+      then('every denylisted ignore is gone', () => {
+        DENYLISTED_IN_FIXTURE.forEach((name) =>
+          expect(scene.ignores).not.toContain(name),
+        );
+      });
+
+      then('the declared ignores and ignorePatterns are present', () => {
+        expect(scene.ignores).toContain('rhachet*');
+        expect(scene.ignores).toContain('declapract');
+        expect(scene.ignores).toContain('yaml');
+        expect(scene.ignorePatterns).toContain('.agent/.actors');
+        expect(scene.ignorePatterns).toContain('!.agent/repo=.this');
+      });
+
+      then('the repo-own ignores survive, with their comments', () => {
+        expect(scene.ignores).toContain('my-own-dep');
+        expect(scene.ignores).toContain('@src/*');
+        expect(scene.after).toContain('# repo-own header comment');
+        expect(scene.after).toContain('# repo-own reason for a repo-own ignore');
+      });
+
+      then('the bad practice is no longer detected on the settled file', () => {
+        expect(() => checkOfDenylist(scene.after, {} as any)).toThrow(
+          'no denylisted packages found in ignores',
+        );
+      });
+
+      then('no declapract template syntax leaked', () => {
+        expect(scene.after).not.toContain('@declapract{');
+      });
+
+      then('the output matches snapshot', () => {
+        expect(scene.after).toMatchSnapshot('.depcheckrc.yml — after');
+      });
+    });
+
+    when('[t2] apply runs a second time', () => {
+      const before = useBeforeAll(async () => ({ contents: await read() }));
+      const scene = useThen('apply again', async () => {
+        await apply();
+        return { after: await read() };
+      });
+
+      then('the file is byte-identical — the apply is a fixed point', () => {
+        expect(scene.after).toEqual(before.contents);
+      });
+    });
+  });
+});