declapract-typescript-ehmpathy 0.49.13 → 0.49.14

package/dist/ancientTargetPublished.declapract.integration.test.ts

@@ -1,12 +1,13 @@
 import { readFileSync } from 'node:fs';
 
+import { MalfunctionError } from 'helpful-errors';
 import { given, then, useBeforeAll, when } from 'test-fns';
-import ts from 'typescript';
+import { getModuleExportsFromTsSource } from './utils/getModuleExportsFromTsSource';
 
 /**
  * .what = exercises case=2's no-404 promise at the reachable grain: the fleet slug an
- *         `sdkAwsLambdaEnvAccess{Ancient,Contemp}` target op RETURNS, for any DEPLOYED access
- *         tier, must be a stage the serverless dual-publish scaffold actually deploys under —
+ *         `sdkAwsLambdaEnvAccess{Ancient,Contemp}` target op RETURNS, for any DEPLOYED access,
+ *         must be a stage the serverless dual-publish scaffold actually deploys under —
  *         so a caller that builds `${service}-${slug}-${fn}` addresses a name a fleet answers
  *         to, never a 404.
  * .why  = case=2 (cross-service-call-never-404s) is a demoed critipath whose core promise is
@@ -51,25 +52,25 @@ const runTargetSlug = (input: {
   name: string;
   access: 'test' | 'prep' | 'prod';
 }): string => {
-  const source = readFileSync(input.path, 'utf8');
-  const transpiled = ts.transpileModule(source, {
-    compilerOptions: {
-      module: ts.ModuleKind.CommonJS,
-      target: ts.ScriptTarget.ES2020,
-    },
-  }).outputText;
-  const moduleExports: Record<string, () => string> = {};
   const requireStub = (id: string): unknown =>
     id.includes('environment') ? { envStatic: { access: input.access } } : {};
-  // eslint-disable-next-line no-new-func
-  new Function('exports', 'require', transpiled)(moduleExports, requireStub);
-  return moduleExports[input.name]();
+  const moduleExports = getModuleExportsFromTsSource<Record<string, () => string>>({
+    source: readFileSync(input.path, 'utf8'),
+    requireStub,
+  });
+  const targetOp =
+    moduleExports[input.name] ??
+    MalfunctionError.throw('the target-op template no longer exports this op', {
+      path: input.path,
+      name: input.name,
+    });
+  return targetOp();
 };
 
 /**
  * .what = the `accessByStage` map, read from the serverless template as { stage: access }.
  * .why  = its KEYS are the `--stage` slugs the scaffold deploys under (the published fleet
- *         slugs); its VALUES are the accesses those deploys reach (the deployed tiers).
+ *         slugs); its VALUES are the accesses those deploys run with (the deployed accesses).
  *         serverless.yml carries `@declapract{...}` vars elsewhere, so a full yaml parse would
  *         choke — the block is clean, so a scoped line-scan reads it exactly.
  */
@@ -93,8 +94,8 @@ describe('the EnvAccess target op emits only slugs the dual-publish scaffold pub
     const state = useBeforeAll(() => {
       const accessByStage = readAccessByStage();
       const publishedStages = Object.keys(accessByStage); // the --stage slugs a deploy publishes
-      const deployedTiers = [...new Set(Object.values(accessByStage))]; // accesses that reach a fleet
-      return { accessByStage, publishedStages, deployedTiers };
+      const deployedAccesses = [...new Set(Object.values(accessByStage))]; // accesses that reach a fleet
+      return { accessByStage, publishedStages, deployedAccesses };
     });
 
     when('the scaffold is read', () => {
@@ -110,18 +111,18 @@ describe('the EnvAccess target op emits only slugs the dual-publish scaffold pub
         expect({
           accessByStage: state.accessByStage,
           publishedStages: [...state.publishedStages].sort(),
-          deployedTiers: [...state.deployedTiers].sort(),
+          deployedAccesses: [...state.deployedAccesses].sort(),
         }).toMatchSnapshot('dual-publish scaffold shape');
       });
     });
 
     when('each deployed access is walked through the ancient target op', () => {
       then('the emitted slug is a stage the scaffold publishes (no 404 by construction)', () => {
-        for (const tier of state.deployedTiers) {
+        for (const deployedAccess of state.deployedAccesses) {
           const slug = runTargetSlug({
             path: ANCIENT_PATH,
             name: 'sdkAwsLambdaEnvAccessAncient',
-            access: tier as 'test' | 'prep' | 'prod',
+            access: deployedAccess as 'test' | 'prep' | 'prod',
           });
           // slug ∈ publishedStages ⟺ the caller's target `${service}-${slug}-${fn}` names a
           // fleet the scaffold actually deploys ⟺ the invoke lands, never a 404
@@ -132,42 +133,42 @@ describe('the EnvAccess target op emits only slugs the dual-publish scaffold pub
 
     when('each deployed access is walked through the contemp target op', () => {
       then('the emitted slug is a stage the scaffold publishes (no 404 by construction)', () => {
-        for (const tier of state.deployedTiers) {
+        for (const deployedAccess of state.deployedAccesses) {
           const slug = runTargetSlug({
             path: CONTEMP_PATH,
             name: 'sdkAwsLambdaEnvAccessContemp',
-            access: tier as 'test' | 'prep' | 'prod',
+            access: deployedAccess as 'test' | 'prep' | 'prod',
           });
           expect(state.publishedStages).toContain(slug);
         }
       });
     });
 
-    when('the per-tier emitted slugs are derived for both target ops', () => {
+    when('the per-access emitted slugs are derived for both target ops', () => {
       // the caller-faced contract of the no-404 invariant: which slug each op emits per deployed
-      // tier, and the published set it must land within. snapshot so a reword that keeps the
-      // membership green (a re-mapped tier, a re-shaped scaffold) reddens a vibecheck.
+      // access, and the published set it must land within. snapshot so a reword that keeps the
+      // membership green (a re-mapped access, a re-shaped scaffold) reddens a vibecheck.
       then('the target-slug shape matches snapshot', () => {
-        const perTier = state.deployedTiers
+        const perAccess = state.deployedAccesses
           .slice()
           .sort()
-          .map((tier) => ({
-            access: tier,
+          .map((deployedAccess) => ({
+            access: deployedAccess,
             ancient: runTargetSlug({
               path: ANCIENT_PATH,
               name: 'sdkAwsLambdaEnvAccessAncient',
-              access: tier as 'test' | 'prep' | 'prod',
+              access: deployedAccess as 'test' | 'prep' | 'prod',
             }),
             contemp: runTargetSlug({
               path: CONTEMP_PATH,
               name: 'sdkAwsLambdaEnvAccessContemp',
-              access: tier as 'test' | 'prep' | 'prod',
+              access: deployedAccess as 'test' | 'prep' | 'prod',
             }),
           }));
         expect({
-          perTier,
+          perAccess,
           publishedStages: [...state.publishedStages].sort(),
-        }).toMatchSnapshot('per-tier target slug vs published stages');
+        }).toMatchSnapshot('per-access target slug vs published stages');
       });
     });
   });

package/dist/bestPracticeTemplateParse.declapract.integration.test.ts

@@ -79,7 +79,40 @@ const asParseErrorLabel = (input: {
  *         literals in every ts template, so they parse as ordinary string content.
  */
 const getAllParseErrors = (input: { path: string; source: string }): string[] =>
-  (
+  getAllSyntacticDiagnostics(input)
+    .filter((diagnostic) => diagnostic.category === ts.DiagnosticCategory.Error)
+    .map((diagnostic) => asParseErrorLabel({ path: input.path, diagnostic }));
+
+/**
+ * .what = the parser's diagnostics for one template, by the route its kind allows.
+ * .why  = `transpileModule` cannot emit a declaration file, so a `.d.ts` template (an ambient
+ *         module, e.g. tests-expo `src/.test/assets/test-fns.autoprune.d.ts`) throws "Output generation failed"
+ *         rather than report. a one-file program's `getSyntacticDiagnostics` reads the same parser
+ *         and accepts a `.d.ts`; it still resolves no module and checks no type.
+ */
+const getAllSyntacticDiagnostics = (input: {
+  path: string;
+  source: string;
+}): readonly ts.Diagnostic[] => {
+  // a declaration file: parse via a one-file program, since it has no emit
+  if (input.path.endsWith('.d.ts')) {
+    const host = ts.createCompilerHost({});
+    const program = ts.createProgram({
+      rootNames: [input.path],
+      options: { noResolve: true, noLib: true },
+      host: {
+        ...host,
+        getSourceFile: (fileName, languageVersion) =>
+          fileName === input.path
+            ? ts.createSourceFile(fileName, input.source, languageVersion)
+            : undefined,
+      },
+    });
+    return program.getSyntacticDiagnostics();
+  }
+
+  // every other template: parse via transpile, which runs the parser only
+  return (
     ts.transpileModule(input.source, {
       fileName: input.path,
       reportDiagnostics: true,
@@ -88,9 +121,8 @@ const getAllParseErrors = (input: { path: string; source: string }): string[] =>
         jsx: ts.JsxEmit.Preserve,
       },
     }).diagnostics ?? []
-  )
-    .filter((diagnostic) => diagnostic.category === ts.DiagnosticCategory.Error)
-    .map((diagnostic) => asParseErrorLabel({ path: input.path, diagnostic }));
+  );
+};
 
 const asLineNumber = (input: { source: string; at: number }): number =>
   input.source.slice(0, input.at).split('\n').length;
@@ -158,6 +190,28 @@ describe('every shipped ts template parses as valid typescript (#613)', () => {
     });
   });
 
+  given('[case3] a declaration-file template (no emit, so no transpile)', () => {
+    when('[t0] a valid ambient module is parsed', () => {
+      then('it reports no error, rather than throw "Output generation failed"', () => {
+        const offenders = getAllParseErrors({
+          path: '/virtual/ok.d.ts',
+          source: "declare module 'x' {\n  export const y: number;\n}\n",
+        });
+        expect(offenders).toEqual([]);
+      });
+    });
+    when('[t1] a broken ambient module is parsed', () => {
+      then('the parser still reports its syntactic error', () => {
+        const offenders = getAllParseErrors({
+          path: '/virtual/broken.d.ts',
+          source: "declare module 'x' {\n  export const y: number\n",
+        });
+        expect(offenders.length).toBeGreaterThan(0);
+        expect(offenders.join('\n')).toContain("'}' expected");
+      });
+    });
+  });
+
   given('[case2] every multi-line jsdoc inside a shipped ts template', () => {
     when('[t0] each block comment is located', () => {
       then('none closes itself mid-line', () => {

package/dist/huskyCommitMsgHook.declapract.integration.test.ts

@@ -0,0 +1,74 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { given, then, when } from 'test-fns';
+import yaml from 'yaml';
+
+import { getAllPracticesForUsecase } from './utils/getAllPracticesForUsecase';
+
+/**
+ * .what = clamps the commit-message hook across every usecase: the `husky` practice ships
+ *         `.husky/commit-msg` + `.husky/check.commit.sh`, and every usecase that holds `husky`
+ *         resolves at least one practice that ships both.
+ * .why  = the commit-msg hook is a hard requirement — it is the one gate that holds every commit
+ *         to the conventional-commits shape the changelog and release version are derived from.
+ *         a dedupe that drops it from one practice without a home in another ships a repo whose
+ *         commits are never linted, and no apply reports the loss.
+ * .teeth = delete either file from `husky/best-practice/.husky/`, or unwire `check.commit.sh` from
+ *          `commit-msg`, and this reddens with the usecase named.
+ */
+
+const repoRoot = join(__dirname, '..');
+const practicesDir = join(repoRoot, 'src/practices');
+const usecasesYmlPath = join(repoRoot, 'src/useCases.yml');
+const HOOK_FILES = ['.husky/commit-msg', '.husky/check.commit.sh'] as const;
+
+/**
+ * .what = the hook files a practice ships from its best-practice dir
+ */
+const getHookFilesShipped = (input: { practice: string }): string[] =>
+  HOOK_FILES.filter((file) =>
+    existsSync(join(practicesDir, input.practice, 'best-practice', file)),
+  );
+
+describe('huskyCommitMsgHook', () => {
+  const usecases = Object.keys(
+    yaml.parse(readFileSync(usecasesYmlPath, 'utf8'))['use-cases'],
+  );
+  const usecasesWithHusky = usecases.filter((usecase) =>
+    getAllPracticesForUsecase({ usecasesYmlPath, usecase }).includes('husky'),
+  );
+
+  given('[case0] the husky practice, the owner of every .husky/ hook', () => {
+    then('it ships commit-msg and check.commit.sh', () => {
+      expect(getHookFilesShipped({ practice: 'husky' })).toEqual([...HOOK_FILES]);
+    });
+
+    then('commit-msg runs check.commit.sh, which runs commitlint on the message', () => {
+      const hookDir = join(practicesDir, 'husky/best-practice/.husky');
+      const commitMsg = readFileSync(join(hookDir, 'commit-msg'), 'utf8');
+      const checkCommit = readFileSync(join(hookDir, 'check.commit.sh'), 'utf8');
+      expect(commitMsg).toContain('/check.commit.sh"');
+      expect(checkCommit).toContain('commitlint --edit "$1"');
+    });
+  });
+
+  given('[case1] each usecase that holds husky', () => {
+    then('at least the core usecase holds it', () => {
+      expect(usecasesWithHusky).toContain('typescript-project-core');
+    });
+
+    when('[t0] its resolved practices are read', () => {
+      then('some practice ships both commit hook files', () => {
+        const offenses = usecasesWithHusky.flatMap((usecase) => {
+          const shipped = getAllPracticesForUsecase({ usecasesYmlPath, usecase })
+            .flatMap((practice) => getHookFilesShipped({ practice }));
+          return HOOK_FILES.filter((file) => !shipped.includes(file)).map(
+            (file) => `${usecase}: no practice ships ${file}`,
+          );
+        });
+        expect(offenses).toEqual([]);
+      });
+    });
+  });
+});

package/dist/integrationApplyScopedOverRealSrc.declapract.integration.test.ts

@@ -0,0 +1,89 @@
+import { readFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+import { given, then, when } from 'test-fns';
+
+import { getAllPathsUnderDir } from './utils/getAllPathsUnderDir';
+
+/**
+ * .what = the argument text of each `<callee>(...)` call in a source, up to its balanced `)`
+ * .why  = the clamp asks of each call what it links or scopes; a balanced scan reads the whole
+ *         argument object, nested braces included, without a parser
+ */
+const getAllCallArgs = (input: { source: string; callee: string }): string[] =>
+  input.source
+    .split(`${input.callee}(`)
+    .slice(1)
+    .map((rest) => {
+      // scan for the `)` that closes this call: depth counts nested `(`, `at` locks the first match
+      const end = [...rest].reduce<{ depth: number; at: number | null }>(
+        (acc, char, index) => {
+          if (acc.at !== null) return acc;
+          if (char === '(') return { ...acc, depth: acc.depth + 1 };
+          if (char !== ')') return acc;
+          if (acc.depth === 0) return { ...acc, at: index };
+          return { ...acc, depth: acc.depth - 1 };
+        },
+        { depth: 0, at: null },
+      ).at;
+      return rest.slice(0, end ?? rest.length);
+    });
+
+/**
+ * .what = whether a genTempDir call mounts a link into this repo's src INSIDE the dir it makes
+ * .why  = a link into src — `src` itself, or a declarations mirror whose `practices/<p>` links back
+ *         to a real practice tree — is a write-through path only where an apply walks it. a mount
+ *         whose slug ends `-declarations` is a separate temp dir beside the applied repo (the
+ *         genTempRepoWithDeclarationsOutside convention), so no apply walks it
+ */
+const isTempDirWithSrcLinkInside = (input: { args: string }): boolean =>
+  /to:\s*'(\.\/)?src\b/.test(input.args) &&
+  !/slug:\s*[`'][^`']*-declarations[`']/.test(input.args);
+
+/**
+ * .what = clamps the write-through class: no integration test mounts a link into this repo's real
+ *         `src` inside a temp repo AND runs an `executeApply` that names no `file`
+ * .why  = an apply walks every path of the repo it applies to, links included, and a fix that
+ *         rewrites `**\/*.ts` writes through the link into this repo's own source.
+ *         old-acceptance-dir-location's test did exactly that: tests-any's `__test_utils__/` →
+ *         `.test.utils/` rewrite reached a fixture and a test file in src. scope each apply with
+ *         `file`, or mount the declarations outside the repo (genTempRepoWithDeclarationsOutside)
+ * .teeth = restore `symlink: [{ at: 'src', to: 'src' }]` in old-acceptance-dir-location's test and
+ *          drop its `file` scope; case1 reddens with that file named.
+ */
+describe('integrationApplyScopedOverRealSrc', () => {
+  const repoRoot = join(__dirname, '..');
+
+  given('[case1] every integration test under src/', () => {
+    when('[t0] each is read', () => {
+      then('none mounts a src link inside its repo and runs an apply with no file scope', () => {
+        const tests = getAllPathsUnderDir({
+          dir: join(repoRoot, 'src'),
+          skip: ['node_modules', '.test'],
+        }).filter((file) => file.endsWith('.integration.test.ts'));
+        expect(tests.length).toBeGreaterThan(10);
+        const offenses = tests
+          .filter((file) => file !== __filename) // this clamp names the pattern it hunts
+          .filter((file) => {
+            const source = readFileSync(file, 'utf8');
+            const linksSrcInside = getAllCallArgs({
+              source,
+              callee: 'genTempDir',
+            }).some((args) => isTempDirWithSrcLinkInside({ args }));
+            if (!linksSrcInside) return false;
+            // a helper that spreads its input is scoped only where that input REQUIRES `file`
+            const spreadIsScoped = /\bfile:\s*string\b/.test(source);
+            return getAllCallArgs({ source, callee: 'executeApply' }).some(
+              (args) => {
+                if (/\bfile\b/.test(args)) return false;
+                if (args.includes('...') && spreadIsScoped) return false;
+                return true;
+              },
+            );
+          })
+          .map((file) => relative(repoRoot, file));
+        expect(offenses).toEqual([]);
+      });
+    });
+  });
+});

package/dist/integrationMountsDeclarationsOutsideSrc.declapract.integration.test.ts

@@ -0,0 +1,72 @@
+import { readFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+import { given, then, when } from 'test-fns';
+
+import { getAllPathsUnderDir } from './utils/getAllPathsUnderDir';
+
+/**
+ * .what = the argument text of each `<callee>(...)` call in a source, up to its balanced `)`
+ * .why  = the clamp asks of each call what it mounts; a balanced scan reads the whole argument
+ *         object, nested braces included, without a parser
+ */
+const getAllCallArgs = (input: { source: string; callee: string }): string[] =>
+  input.source
+    .split(`${input.callee}(`)
+    .slice(1)
+    .map((rest) => {
+      // scan for the `)` that closes this call: depth counts nested `(`, `at` locks the first match
+      const end = [...rest].reduce<{ depth: number; at: number | null }>(
+        (acc, char, index) => {
+          if (acc.at !== null) return acc;
+          if (char === '(') return { ...acc, depth: acc.depth + 1 };
+          if (char !== ')') return acc;
+          if (acc.depth === 0) return { ...acc, at: index };
+          return { ...acc, depth: acc.depth - 1 };
+        },
+        { depth: 0, at: null },
+      ).at;
+      return rest.slice(0, end ?? rest.length);
+    });
+
+/**
+ * .what = whether a genTempDir call mounts this repo's `src` at the demo repo's own `src`
+ * .why  = that mount is the one shape that makes the demo repo's `src` BE this whole library
+ */
+const isTempDirWithSrcMountedAtSrc = (input: { args: string }): boolean =>
+  /at:\s*'src'\s*,\s*to:\s*'(\.\/)?src'/.test(input.args);
+
+/**
+ * .what = clamps the mount class: no integration test mounts this repo's `src` at the demo repo's
+ *         own `src`; the declarations mount at `declarations` instead
+ * .why  = a demo repo whose `src` IS this repo's src makes every `src/**` wildcard declaration scan
+ *         the whole library, so each apply runs minutes and times out under suite load
+ *         (legacy-change-id: 899s → 66s once re-mounted at `declarations`)
+ * .teeth = restore `symlink: [{ at: 'src', to: 'src' }]` in any one converted suite (e.g. logs) and
+ *          case1 reddens with that file named.
+ */
+describe('integrationMountsDeclarationsOutsideSrc', () => {
+  const repoRoot = join(__dirname, '..');
+
+  given('[case1] every integration test under src/', () => {
+    when('[t0] each is read', () => {
+      then('none mounts this repo src at the demo repo src', () => {
+        const tests = getAllPathsUnderDir({
+          dir: join(repoRoot, 'src'),
+          skip: ['node_modules', '.test'],
+        }).filter((file) => file.endsWith('.integration.test.ts'));
+        expect(tests.length).toBeGreaterThan(10);
+        const offenses = tests
+          .filter((file) => file !== __filename) // this clamp names the pattern it hunts
+          .filter((file) =>
+            getAllCallArgs({
+              source: readFileSync(file, 'utf8'),
+              callee: 'genTempDir',
+            }).some((args) => isTempDirWithSrcMountedAtSrc({ args })),
+          )
+          .map((file) => relative(repoRoot, file));
+        expect(offenses).toEqual([]);
+      });
+    });
+  });
+});

package/dist/packageCommandsCallDeclaredBins.declapract.integration.test.ts

@@ -0,0 +1,176 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { given, then, when } from 'test-fns';
+import yaml from 'yaml';
+
+import { getAllPracticesForUsecase } from './utils/getAllPracticesForUsecase';
+
+/**
+ * .what = clamps #672 across every practice: a package command a practice declares calls the bin
+ *         of a declared dep by its bare name, never through `npx`. a dep counts as declared when the
+ *         practice itself declares it, or a practice that every usecase which holds it also holds.
+ * .why  = under `pnpm run`, pnpm exports its own settings as `npm_config_*` vars; `npx` is npm, so
+ *         it reads them and prints an `Unknown env config` warn above every command. a package command
+ *         already has `node_modules/.bin` on its PATH, so the bare bin finds the pinned dep — and
+ *         fails loud when the dep is absent, where `npx` would fetch one from the registry.
+ * .teeth = put `npx ` back in front of any declared bin (e.g. `npx sls prune` in serverless, or
+ *          `npx sql-schema-control plan` in persist-with-rds) and case1 reddens with the practice,
+ *          the command, and the bin named. add an `npx <bin>` whose package no co-held practice
+ *          declares, with no reason on record, and case2 reddens.
+ * .note = each subject is a shipped TEMPLATE (a CONTAINS check on package.json). declapract's json
+ *         fix replaces a mismatched string value in place, so an adopter's extant `npx x` command is
+ *         flagged by the check and rewritten by the next apply — it converges, never sticks.
+ */
+
+const repoRoot = join(__dirname, '..');
+const practicesDir = join(repoRoot, 'src/practices');
+const usecasesYmlPath = join(repoRoot, 'src/useCases.yml');
+
+/**
+ * .what = the package that provides each bin a template calls through npx
+ * .why  = a bin name and its package name often differ (`sls` from serverless, `cz` from
+ *         commitizen), so the clamp needs the map to know whether the bin's package is declared
+ */
+const PACKAGE_BY_BIN: Record<string, string> = {
+  sls: 'serverless',
+  serverless: 'serverless',
+  'sdk-environment': 'sdk-environment',
+  expo: 'expo',
+  'dynamodb-dao-generator': 'dynamodb-dao-generator',
+  'simple-artifact-builder': 'simple-artifact-builder',
+  'sql-schema-control': 'sql-schema-control',
+  cz: 'commitizen',
+  commitlint: '@commitlint/cli',
+  depcheck: 'depcheck',
+  'wait-on': 'wait-on',
+  'local-ssl-proxy': 'local-ssl-proxy',
+  serve: 'serve',
+  eas: 'eas-cli',
+};
+
+/**
+ * .what = each bin a template may still call through npx, with the reason it stays
+ * .why  = an npx call is only correct where no co-held practice declares the bin's package; the
+ *         reason is the record of that decision, so a later reader need not re-derive it
+ */
+const NPX_KEPT_BY_BIN: Record<string, string> = {
+  cz: 'conventional-commits declares cz-conventional-changelog (the adapter), not commitizen (the cz bin); pnpm links no transitive bin into node_modules/.bin',
+  'local-ssl-proxy':
+    'cicd-app-react-native-expo declares no local-ssl-proxy; npx fetches it on demand for a local dev proxy',
+  serve:
+    'cicd-app-react-native-expo declares no serve; npx fetches it on demand for a local preview of dist',
+  eas: 'cicd-app-react-native-expo declares no eas-cli; eas is an expo-hosted cli, fetched by npx (or a global install)',
+};
+
+type PackageJson = {
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+  scripts?: Record<string, string>;
+};
+
+/**
+ * .what = one practice's best-practice package.json, or null where it declares none
+ */
+const getOnePracticePackageJson = (input: {
+  practice: string;
+}): PackageJson | null => {
+  const path = join(practicesDir, input.practice, 'best-practice/package.json');
+  if (!existsSync(path)) return null;
+  return JSON.parse(readFileSync(path, 'utf8'));
+};
+
+/**
+ * .what = the practices that every usecase which holds this practice also holds (itself included)
+ * .why  = a dep declared by a co-held practice is present in every repo that runs this command
+ */
+const getAllCoHeldPractices = (input: {
+  practice: string;
+  usecases: string[];
+}): string[] => {
+  const holders = input.usecases
+    .map((usecase) => getAllPracticesForUsecase({ usecasesYmlPath, usecase }))
+    .filter((practices) => practices.includes(input.practice));
+  if (!holders.length) return [input.practice];
+  return holders.reduce((shared, practices) =>
+    shared.filter((practice) => practices.includes(practice)),
+  );
+};
+
+/**
+ * .what = the dep names a set of practices declare, across dependencies and devDependencies
+ */
+const getAllDeclaredDeps = (input: { practices: string[] }): string[] =>
+  input.practices.flatMap((practice) => {
+    const pkg = getOnePracticePackageJson({ practice });
+    return [
+      ...Object.keys(pkg?.dependencies ?? {}),
+      ...Object.keys(pkg?.devDependencies ?? {}),
+    ];
+  });
+
+/**
+ * .what = the bins a command calls through npx, e.g. `npx sls prune` → ['sls']
+ */
+const getAllNpxBins = (input: { command: string }): string[] =>
+  [...input.command.matchAll(/(?:^|[\s(;&|])npx ([@\w./-]+)/g)].map(
+    (match) => match[1]!,
+  );
+
+describe('package commands call declared bins bare, across every practice (#672)', () => {
+  const usecases = Object.keys(
+    yaml.parse(readFileSync(usecasesYmlPath, 'utf8'))['use-cases'],
+  );
+  const npxCalls = readdirSync(practicesDir).flatMap((practice) => {
+    const pkg = getOnePracticePackageJson({ practice });
+    if (!pkg) return [];
+    const declaredDeps = getAllDeclaredDeps({
+      practices: getAllCoHeldPractices({ practice, usecases }),
+    });
+    return Object.entries(pkg.scripts ?? {}).flatMap(([commandName, command]) =>
+      getAllNpxBins({ command }).map((bin) => ({
+        practice,
+        commandName,
+        bin,
+        declared: declaredDeps.includes(PACKAGE_BY_BIN[bin] ?? bin),
+      })),
+    );
+  });
+
+  given('[case1] an npx call whose package a co-held practice declares', () => {
+    when('every shipped package.json template is read', () => {
+      then('no command calls a declared bin through npx', () => {
+        const offenders = npxCalls.filter((call) => call.declared);
+        expect(offenders).toEqual([]);
+      });
+    });
+  });
+
+  given('[case2] an npx call whose package no co-held practice declares', () => {
+    when('every shipped package.json template is read', () => {
+      then('each such bin is on record with the reason it stays npx', () => {
+        const unrecorded = npxCalls.filter(
+          (call) => !call.declared && !NPX_KEPT_BY_BIN[call.bin],
+        );
+        expect(unrecorded).toEqual([]);
+      });
+    });
+  });
+
+  given('[case3] the persist-with-rds provision:schema commands', () => {
+    const pkg = getOnePracticePackageJson({ practice: 'persist-with-rds' });
+    when('the template is read', () => {
+      then('they call sql-schema-control bare', () => {
+        expect(pkg?.scripts?.['provision:schema:plan']).toEqual(
+          'sql-schema-control plan -c provision/schema/control.yml',
+        );
+        expect(pkg?.scripts?.['provision:schema:apply']).toEqual(
+          'sql-schema-control apply -c provision/schema/control.yml',
+        );
+        expect(pkg?.scripts?.['provision:schema:sync']).toEqual(
+          'sql-schema-control sync -c provision/schema/control.yml',
+        );
+      });
+    });
+  });
+});

package/dist/parsePackageJSONAdoption.declapract.integration.test.ts

@@ -67,7 +67,6 @@ const ALLOWED_UNCONVERTED = [
   'node-service/bad-practices/license/package.json.declapract.ts',
   'node-service/bad-practices/simple-lambda-client/package.json.declapract.ts',
   'node-service/bad-practices/simple-lambda-handlers/package.json.declapract.ts',
-  'node/bad-practices/self-deps-not-link/package.json.declapract.ts',
   'package-json-order/best-practice/package.json.declapract.ts',
   'persist-with-rds/bad-practices/old-packagejson-script-names/package.json.declapract.ts',
   'pnpm/bad-practices/npm-overrides/package.json.declapract.ts',