declapract-typescript-ehmpathy 0.49.11 → 0.49.13

package/dist/practices/rhachet/boot-refs-glossary.declapract.integration.test.ts

@@ -0,0 +1,89 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { given, then, when } from 'test-fns';
+
+/**
+ * .what = clamps that the rhachet practice's shipped boot.yml defaults every brief to SAY level and
+ *         refs ONLY the deep glossary variants (`.reason`, `.example`), via GLOBs — never this repo's
+ *         enumerated term list, and never a `say:` enumeration.
+ * .why  = the boot.yml is a TEMPLATE copied to every consumer. under #105 the shape is SIMPLE mode
+ *         with `say` ABSENT + `ref` present, so the loader reads every discovered brief at say-level
+ *         EXCEPT the ref-matched deep variants. the ref entries must be globs (matched against the
+ *         consumer's tree by rhachet's fast-glob), never a hardcoded list of THIS repo's terms -- an
+ *         enumerated list would ref terms a consumer does not have and miss the ones it does. a glob
+ *         is also drift-proof: a new term's deep variants auto-demote, and no say entry is ever
+ *         enumerated.
+ * .teeth = swap a `term=*` deep-variant glob for an enumerated `term=convergence._.choice.reason.md`
+ *          and the "no hardcoded term name" case reddens; add a `say:` key and the "no say
+ *          enumeration" case reddens; add an `always:` key and the "simple mode" case reddens; ref
+ *          the `._.choice._.md` root (a say-level brief) and the "choice root stays say" case reddens.
+ * .note = the subject is the shipped TEMPLATE text. the `.integration.test.ts` suffix reads the
+ *         filesystem (a remote boundary); this file sits at the practice ROOT (not under
+ *         best-practice/), so it is neither loaded as a declaration nor copied to a consumer.
+ * .note = this supersedes the #587 ref-all clamp: #587 refed the whole glossary (choice root +
+ *         readme) for a near-zero boot cost; #105 flips the default to say and refs only the
+ *         reason/example deep variants. the assertions below encode the #105 shape.
+ */
+
+// anchor on __dirname, not process.cwd(): a nested `jest src/practices/...` run has a different cwd.
+// from this file (src/practices/rhachet/) the best-practice tree is one segment down.
+const bootYmlPath = join(
+  __dirname,
+  'best-practice/.agent/repo=.this/role=any/boot.yml',
+);
+
+const REASON_REF = 'briefs/domain.terms/term=*._.choice.reason.md';
+const EXAMPLE_REF = 'briefs/domain.terms/term=*._.choice.example=*.md';
+const CHOICE_ROOT_REF = 'briefs/domain.terms/term=*._.choice._.md';
+
+describe('rhachet boot.yml defaults to say, refs only deep glossary variants', () => {
+  given('[case1] the shipped boot.yml template', () => {
+    const contents = readFileSync(bootYmlPath, 'utf8');
+
+    when('[t0] the template is read', () => {
+      then('it is simple mode (top-level briefs:, no always:)', () => {
+        expect(contents).toMatch(/^briefs:/m);
+        expect(contents).not.toMatch(/^always:/m);
+      });
+
+      then('it enumerates no say entry (say defaults for every brief)', () => {
+        // the whole point of #105: `say` is absent, so the loader defaults every discovered brief to
+        // say. a `say:` key would enumerate — exactly what #105 forbids.
+        expect(contents).not.toMatch(/^\s*say:/m);
+      });
+
+      then('it refs the deep glossary variants via globs', () => {
+        expect(contents).toContain(REASON_REF);
+        expect(contents).toContain(EXAMPLE_REF);
+      });
+
+      then('it does not ref the choice root (it stays say-level)', () => {
+        // the `._.choice._.md` root is the say-lean brief a consumer wants in context; only the
+        // reason-deep + example variants demote to ref.
+        expect(contents).not.toContain(CHOICE_ROOT_REF);
+      });
+
+      then('it hardcodes no specific term name (stays per-consumer correct)', () => {
+        // a concrete `term=<slug>._.choice...` (slug != the `*` glob) would be this repo's own term,
+        // wrong for a consumer. the only legal `term=` token is the glob wildcard.
+        const concreteTermRefs = (
+          contents.match(/term=[a-z][a-z-]*\._\.choice/g) || []
+        ).filter((m) => !m.startsWith('term=*'));
+        expect(concreteTermRefs).toEqual([]);
+      });
+
+      then('the emitted glossary ref lines match snapshot', () => {
+        // snapshot the governed glossary ref lines themselves, so a reshaped ref that keeps the glob
+        // tokens green (a reordered entry, a rephrased comment) reddens a vibecheck in review
+        // (rule.require.contract-snapshot-exhaustiveness)
+        const refLines = contents
+          .split('\n')
+          .filter((line) => line.includes('domain.terms/'))
+          .map((line) => line.trim())
+          .join('\n');
+        expect(refLines).toMatchSnapshot('boot.yml glossary refs');
+      });
+    });
+  });
+});

package/dist/practices/rhachet/boot-yml-findsert.declapract.integration.test.ts

@@ -0,0 +1,145 @@
+import fs from 'fs/promises';
+import path from 'node:path';
+
+import { executeApply } from 'declapract';
+// eslint-disable-next-line import/no-extraneous-dependencies
+import yaml from 'yaml';
+import { genTempDir, given, then, useThen, when } from 'test-fns';
+
+/**
+ * .what = end-to-end proof of the boot.yml FINDSERT (#105 req 1), run through the REAL declapract
+ *         apply pipeline against a genTempDir clone of a consumer whose boot.yml already carries its
+ *         OWN say + ref entries.
+ * .why  = req 1 is that the boot.yml is only ever findserted into a consumer, never whole-file
+ *         overwritten — so a consumer's own boot entries survive. per
+ *         `rule.require.declapract-integration-tests`, a `fix` with logic (a yaml union that reads the
+ *         consumer's extant file) owes a pipeline test: a unit test of the exported `fix` never
+ *         exercises the glob→file match nor the apply against a real consumer file. this is that test.
+ * .note = the consumer boot is SIMPLE mode with a `say` pick and a `ref` pick of its own. the
+ *         after-state proves both declared deep-variant globs are unioned in AND both consumer picks
+ *         survive byte-for-value — the whole-file-overwrite failure this guards against would drop them.
+ * .note = the boot is snapshotted in full (before AND after) so a reviewer can eyeball the exact
+ *         end-state (`rule.require.snapshots`).
+ */
+describe('rhachet — boot.yml findsert (req 1: consumer entries survive)', () => {
+  given("[case1] a consumer whose boot.yml carries its own entries", () => {
+    const tempDir = genTempDir({
+      slug: 'declapract-rhachet-boot-findsert',
+      clone:
+        './src/practices/rhachet/.test/assets/demo-repo-with-consumer-boot',
+      symlink: [{ at: 'src', to: 'src' }],
+    });
+
+    const bootPath = '.agent/repo=.this/role=any/boot.yml';
+    const REASON_REF = 'briefs/domain.terms/term=*._.choice.reason.md';
+    const EXAMPLE_REF = 'briefs/domain.terms/term=*._.choice.example=*.md';
+
+    const read = (relativePath: string) =>
+      fs.readFile(path.join(tempDir, relativePath), 'utf-8');
+    const applyFix = () =>
+      executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'rhachet',
+        file: bootPath,
+      });
+
+    when('[t0] the input (before any fix)', () => {
+      then('the consumer boot.yml carries its own picks, no budget, + matches snapshot', async () => {
+        const before = await read(bootPath);
+        expect(before).toContain('briefs/my-own-brief.md');
+        expect(before).toContain('briefs/my-own-deep-variant.md');
+        // the consumer predates the budget cap — it carries none (the findsert-add path)
+        expect(yaml.parse(before).budget).toBeUndefined();
+        expect(before).toMatchSnapshot('boot.yml — before');
+      });
+    });
+
+    when('[t1] the findsert fix is applied', () => {
+      useThen('union the declared deep-variant globs into the consumer boot', async () =>
+        applyFix(),
+      );
+
+      then(
+        "both declared globs land AND the consumer's own say + ref picks survive, and it matches snapshot",
+        async () => {
+          const after = await read(bootPath);
+          const parsed = yaml.parse(after);
+
+          // the two declared deep-variant globs were unioned into the consumer's ref list
+          expect(parsed.briefs.ref).toContain(REASON_REF);
+          expect(parsed.briefs.ref).toContain(EXAMPLE_REF);
+          // the consumer's OWN ref pick survives (the whole-overwrite failure would drop it)
+          expect(parsed.briefs.ref).toContain('briefs/my-own-deep-variant.md');
+          // the consumer's OWN say pick survives untouched
+          expect(parsed.briefs.say).toContain('briefs/my-own-brief.md');
+          // it stayed simple mode — the fix created no top-level always: key
+          expect(parsed.always).toBeUndefined();
+          // the budget cap was findserted into a consumer that predated it
+          expect(parsed.budget.tokens).toEqual(5_000);
+          // full content, for the reviewer's eye
+          expect(after).toMatchSnapshot('boot.yml — after');
+        },
+      );
+    });
+
+    when('[t2] the fix is applied a second time (idempotency)', () => {
+      // once both globs are present, the check passes and the fix is a no-op — the boot must be
+      // byte-identical across a re-apply (`rule.require.idempotent-fixes`).
+      const passes = useThen(
+        'a second apply over its own output',
+        async () => {
+          const before = await read(bootPath);
+          await applyFix();
+          const after = await read(bootPath);
+          return { before, after };
+        },
+      );
+
+      then('the second apply is a no-op', () => {
+        expect(passes.after).toEqual(passes.before);
+      });
+    });
+  });
+
+  given("[case2] a consumer whose boot.yml already declares a divergent budget", () => {
+    const tempDir = genTempDir({
+      slug: 'declapract-rhachet-boot-budget-preserved',
+      clone:
+        './src/practices/rhachet/.test/assets/demo-repo-with-consumer-boot',
+      symlink: [{ at: 'src', to: 'src' }],
+    });
+
+    const bootPath = '.agent/repo=.this/role=any/boot.yml';
+    const bootAbs = path.join(tempDir, bootPath);
+
+    const applyFix = () =>
+      executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'rhachet',
+        file: bootPath,
+      });
+
+    // seed the writable clone with a budget the consumer chose on purpose — a value the findsert
+    // must NOT revert (findsert, never upsert). this proves the present-value-preserved branch
+    // through the real pipeline, no extra fixture needed.
+    when('[t0] the consumer set its own budget of 9000', () => {
+      useThen('write a divergent budget into the cloned boot', async () => {
+        const before = await fs.readFile(bootAbs, 'utf-8');
+        await fs.writeFile(bootAbs, `${before}budget:\n  tokens: 9000\n`, 'utf-8');
+      });
+
+      then('the seed carries the consumer budget', async () => {
+        expect(yaml.parse(await fs.readFile(bootAbs, 'utf-8')).budget.tokens).toEqual(9000);
+      });
+    });
+
+    when('[t1] the findsert fix is applied', () => {
+      useThen('apply the fix over the consumer-chosen budget', async () => applyFix());
+
+      then("the consumer's budget survives untouched (findsert, never upsert)", async () => {
+        const parsed = yaml.parse(await fs.readFile(bootAbs, 'utf-8'));
+        expect(parsed.budget.tokens).toEqual(9000);
+      });
+    });
+  });
+});

package/dist/practices/runtime-schemas/bad-practices/joi/.declapract.integration.test.ts

@@ -0,0 +1,102 @@
+import fs from 'fs/promises';
+import path from 'node:path';
+
+import { executeApply } from 'declapract';
+import { genTempDir, given, then, useThen, when } from 'test-fns';
+
+// executeApply is slow (full practice evaluation), so grant a generous limit
+jest.setTimeout(180_000);
+
+/**
+ * .what = end-to-end proof of the joi->zod migration, run through the REAL declapract apply
+ *   pipeline against a genTempDir clone of a consumer repo. per
+ *   rule.require.declapract-integration-tests, a fix that TRANSFORMS a file (regex rewrite + a
+ *   value-rewrite @declapract:review marker) owes a pipeline test — a unit test of the exported
+ *   `fix` never exercises the source-file glob -> file match, nor that the marker lands on disk.
+ * .why = the shape-for-shape rewrite makes three silent semantic changes a regex cannot get right
+ *   (optionality, unknown-key policy, date coercion), so the fix prepends a @declapract:review
+ *   marker that names them rather than ship a silent guess (#594).
+ * .note = the target file is snapshotted in full (before AND after), so a reviewer can eyeball the
+ *   exact end-state, per rule.require.declapract-integration-tests.
+ * .teeth = the input imports joi + declares a `Joi.object` schema. the after-state proves the import
+ *   is rewritten to `zod`, the `Joi.*` calls become `z.*`, and the @declapract:review marker lands
+ *   on disk — the glue a mocked-context unit test cannot show.
+ */
+describe('joi->zod migration', () => {
+  given('[case1] a repo with a joi schema in a src file', () => {
+    const tempDir = genTempDir({
+      slug: 'declapract-joi',
+      clone: './src/practices/runtime-schemas/bad-practices/joi/.test/assets/demo-repo-with-joi',
+      symlink: [
+        {
+          at: 'declarations',
+          to: './src/.test/assets/runtime-schemas/declarations',
+        },
+        { at: 'node_modules', to: 'node_modules' },
+      ],
+    });
+
+    const targetPath = 'src/contract/schemas/widget.schema.ts';
+    const read = (relativePath: string) =>
+      fs.readFile(path.join(tempDir, relativePath), 'utf-8');
+    const applyMigrate = () =>
+      executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'runtime-schemas',
+        file: targetPath,
+      });
+
+    when('[t0] the migration input (before any fix)', () => {
+      then('the src file imports joi + declares a Joi schema + matches snapshot', async () => {
+        const before = await read(targetPath);
+        expect(before).toContain("from 'joi'");
+        expect(before).toContain('Joi.object(');
+        expect(before).not.toContain('@declapract:review');
+        expect(before).toMatchSnapshot('widget.schema.ts — before');
+      });
+    });
+
+    when('[t1] the joi fix is applied', () => {
+      useThen('migrate the joi schema to zod', async () => applyMigrate());
+
+      then(
+        'the import + schema are rewritten to zod, the review marker lands, and it matches snapshot',
+        async () => {
+          const after = await read(targetPath);
+
+          // the import is rewritten to zod
+          expect(after).toContain("import { z } from 'zod'");
+          expect(after).not.toContain("from 'joi'");
+
+          // the Joi.* schema calls become z.*
+          expect(after).toContain('z.object(');
+          expect(after).not.toContain('Joi.object(');
+
+          // the value-rewrite marker lands on disk — the three silent semantic guesses
+          // (optionality, unknown keys, date coercion) are loud, per #594
+          expect(after).toContain('@declapract:review');
+          expect(after).toContain('optionality');
+
+          // full content, for the reviewer's eye
+          expect(after).toMatchSnapshot('widget.schema.ts — after');
+        },
+      );
+    });
+
+    when('[t2] the fix is applied a second time (idempotency)', () => {
+      // post-rewrite the file imports from zod, so the check no longer detects the bad practice and
+      // the fix does not run — the second apply changes zero bytes, and the marker is never
+      // double-prepended (per rule.require.idempotent-fixes).
+      const passes = useThen('a second apply over its own output', async () => {
+        const before = await read(targetPath); // post-first-migrate
+        await applyMigrate(); // second apply
+        const after = await read(targetPath);
+        return { before, after };
+      });
+
+      then('the second apply is a no-op', () => {
+        expect(passes.after).toEqual(passes.before);
+      });
+    });
+  });
+});

package/dist/practices/runtime-schemas/bad-practices/joi/.test/assets/demo-repo-with-joi/declapract.use.yml

@@ -0,0 +1,5 @@
+# .note = the declarations dir is symlinked by the test (holds declapract.declare.yml + a
+#         practices/runtime-schemas symlink to the real practice), so the consumer's own src/ tree
+#         stays free to hold the target .ts file the src/**/*.ts glob matches.
+declarations: 'declarations/declapract.declare.yml'
+useCase: lambda-service

package/dist/practices/runtime-schemas/bad-practices/joi/.test/assets/demo-repo-with-joi/package.json

@@ -0,0 +1,4 @@
+{
+  "name": "test-project",
+  "version": "1.0.0"
+}

package/dist/practices/runtime-schemas/bad-practices/joi/.test/assets/demo-repo-with-joi/src/contract/schemas/widget.schema.ts

@@ -0,0 +1,9 @@
+import Joi from 'joi';
+
+// a joi schema — the shape-for-shape rewrite to zod makes three silent semantic
+// changes a regex cannot get right, so the fix prepends a loud review marker.
+export const widgetSchema = Joi.object({
+  name: Joi.string().required(),
+  count: Joi.number(),
+  createdAt: Joi.date(),
+});

package/dist/practices/runtime-schemas/bad-practices/joi/__snapshots__/.declapract.integration.test.ts.snap

@@ -0,0 +1,37 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`joi->zod migration given: [case1] a repo with a joi schema in a src file when: [t0] the migration input (before any fix) then: the src file imports joi + declares a Joi schema + matches snapshot: widget.schema.ts — before 1`] = `
+"import Joi from 'joi';
+
+// a joi schema — the shape-for-shape rewrite to zod makes three silent semantic
+// changes a regex cannot get right, so the fix prepends a loud review marker.
+export const widgetSchema = Joi.object({
+  name: Joi.string().required(),
+  count: Joi.number(),
+  createdAt: Joi.date(),
+});
+"
+`;
+
+exports[`joi->zod migration given: [case1] a repo with a joi schema in a src file when: [t1] the joi fix is applied then: the import + schema are rewritten to zod, the review marker lands, and it matches snapshot: widget.schema.ts — after 1`] = `
+"/**
+ * @declapract:review — auto-migrated to zod; VERIFY these three semantics by hand:
+ *  - optionality: a source field with no explicit required marker was OPTIONAL, but the zod field
+ *    is now REQUIRED by default. re-mark any truly-optional field \`.optional()\`.
+ *  - unknown keys: the prior \`.object()\` rejected unknown keys; \`z.object()\` strips them silently.
+ *    use \`z.looseObject()\` only where the shape must pass unknown keys through.
+ *  - date coercion: the prior \`.date()\` coerced strings to Date; \`z.date()\` rejects a string.
+ *    use \`z.coerce.date()\` where the input arrives as a string.
+ * delete this marker once each point is verified.
+ */
+import { z } from 'zod';
+
+// a joi schema — the shape-for-shape rewrite to zod makes three silent semantic
+// changes a regex cannot get right, so the fix prepends a loud review marker.
+export const widgetSchema = z.object({
+  name: z.string(),
+  count: z.number(),
+  createdAt: z.date(),
+});
+"
+`;

package/dist/practices/runtime-schemas/bad-practices/joi/src/<star><star>/<star>.ts.declapract.ts

@@ -14,15 +14,38 @@ export const check: FileCheckFunction = (contents) => {
 };
 
 /**
- * .what = transforms joi imports and basic schema patterns to zod
- * .why = automated migration reduces manual toil
+ * .what = a loud marker prepended to every rewritten file, so the three SILENT semantic
+ *         changes this mechanical rewrite makes become visible to the consumer.
+ * .why = the rewrite is a regex, and a regex cannot know a field's intended optionality, its
+ *        unknown-key policy, or whether a date arrives as a string. it therefore GUESSES, and each
+ *        guess typechecks. per the value-rewrite guard, a rewrite that must guess emits a review
+ *        marker rather than a silent, possibly-wrong result (#594). the consumer deletes the marker
+ *        once each point is verified by hand.
+ */
+const reviewMarker = `/**
+ * @declapract:review — auto-migrated to zod; VERIFY these three semantics by hand:
+ *  - optionality: a source field with no explicit required marker was OPTIONAL, but the zod field
+ *    is now REQUIRED by default. re-mark any truly-optional field \`.optional()\`.
+ *  - unknown keys: the prior \`.object()\` rejected unknown keys; \`z.object()\` strips them silently.
+ *    use \`z.looseObject()\` only where the shape must pass unknown keys through.
+ *  - date coercion: the prior \`.date()\` coerced strings to Date; \`z.date()\` rejects a string.
+ *    use \`z.coerce.date()\` where the input arrives as a string.
+ * delete this marker once each point is verified.
+ */
+`;
+
+/**
+ * .what = transforms joi imports and basic schema patterns to zod, with a review marker
+ * .why = automated migration reduces manual toil, but the shape-for-shape rewrite makes three
+ *        silent semantic changes a regex cannot get right — so it prepends a @declapract:review
+ *        marker that flags them, rather than ship a silent guess (#594).
  *
  * .note = basic transforms only; complex patterns require manual fix
  */
 export const fix: FileFixFunction = (contents) => {
   if (!contents) return {};
 
-  const updated = contents
+  const transformed = contents
     // transform imports: import Joi from 'joi' → import { z } from 'zod'
     .replace(/import\s+Joi\s+from\s+['"]joi['"]/g, "import { z } from 'zod'")
     // transform imports: import * as Joi from 'joi' → import { z } from 'zod'
@@ -46,5 +69,11 @@ export const fix: FileFixFunction = (contents) => {
     // transform .required() → remove (zod is required by default)
     .replace(/\.required\(\)/g, '');
 
+  // prepend the review marker once, so the silent semantic guesses are loud (idempotent: the
+  // check no longer fires post-rewrite, and a second pass would find the marker already present)
+  const updated = transformed.includes('@declapract:review')
+    ? transformed
+    : reviewMarker + transformed;
+
   return { contents: updated };
 };