declapract-typescript-ehmpathy 0.49.12 → 0.49.14

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',

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

@@ -0,0 +1,388 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+import { genTempDir, given, then, when } from 'test-fns';
+
+import {
+  getAllPathsUnderDir,
+  PRACTICE_TREE_SKIP_DIRS,
+} from './utils/getAllPathsUnderDir';
+
+/**
+ * .what = two sweeps over every declaration every practice ships:
+ *         1. no check can fail with no fix behind it, unless the gap is on the allowlist with its reason (#607)
+ *         2. every custom fix is a fixed point on the declared input, and its own check settles on
+ *            what it wrote: fix(fix(x)) === fix(x); a best-practice check passes on fix(x), and a
+ *            bad-practice check no longer detects its pattern there (#536, #607)
+ * .why  = when any failed check on a file has no fix, declapract marks the WHOLE file manual and
+ *         applies none of its fixes, so one unfixable declaration silently blocks every other
+ *         practice's fix on that file (#607). a fix that is not a fixed point rewrites a file on
+ *         every apply, so `declapract apply` never converges (#536).
+ * .teeth = drop the `fix` export from `lint/best-practice/.dpdmrc.yaml.declapract.ts` and case1
+ *          goes red with that path; make the terraform-formatter fix append a key and case2 goes
+ *          red with that path; make the bottleneck bad-practice fix return its input and case2 goes
+ *          red with "the bad-practice check still detects on fix(x)".
+ * .note = the fix of each declaration mirrors declapract's own getFileCheckDeclaration: a declared
+ *         `fix` wins; else EQUALS (best-practice) writes the template, CONTAINS on a `.json` merges
+ *         keys, CONTAINS on any other path writes only when the file is absent, EXISTS
+ *         (bad-practice) deletes the file, and every other shape has no fix.
+ */
+
+const practicesDir = join(__dirname, 'practices');
+
+type Purpose = 'best-practice' | 'bad-practice';
+
+interface Declaration {
+  practice: string;
+  purpose: Purpose;
+  /**
+   * the dir the declared path is relative to (a best-practice dir, or one bad-practice dir)
+   */
+  root: string;
+  /**
+   * the declared path, relative to its root
+   */
+  path: string;
+}
+
+/**
+ * .what = the shape of what a `.declapract.ts` module exports
+ */
+interface DeclarationModule {
+  check?: unknown;
+  fix?: unknown;
+}
+
+type FixFn = (
+  contents: string | null,
+  context: Record<string, unknown>,
+) =>
+  | Promise<{ contents?: string | null }>
+  | { contents?: string | null };
+
+type CheckFn = (
+  contents: string | null,
+  context: Record<string, unknown>,
+) => unknown;
+
+/**
+ * .what = the declaration roots of a practice: its best-practice dir and each bad-practice dir
+ */
+const getAllDeclarationRoots = (input: {
+  practice: string;
+}): { purpose: Purpose; root: string }[] => {
+  const best = join(practicesDir, input.practice, 'best-practice');
+  const badDir = join(practicesDir, input.practice, 'bad-practices');
+  const bestRoots = existsSync(best)
+    ? [{ purpose: 'best-practice' as const, root: best }]
+    : [];
+  const badRoots = existsSync(badDir)
+    ? readdirSync(badDir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => ({
+          purpose: 'bad-practice' as const,
+          root: join(badDir, entry.name),
+        }))
+    : [];
+  return [...bestRoots, ...badRoots];
+};
+
+/**
+ * .what = every declaration in every practice, one per declared path
+ * .note = mirrors declapract's read of a declaration dir: every file is a declaration except the
+ *         root `.declapract.*` meta files and the `*.declapract.test.ts(.snap)` files compile strips.
+ *         a `*.declapract.integration.test.ts` is a test too, so it is skipped here as well
+ */
+const getAllDeclarations = (): Declaration[] =>
+  readdirSync(practicesDir)
+    .sort()
+    .flatMap((practice) =>
+      getAllDeclarationRoots({ practice }).flatMap(({ purpose, root }) => {
+        const paths = getAllPathsUnderDir({
+          dir: root,
+          skip: PRACTICE_TREE_SKIP_DIRS,
+        })
+          .map((path) => relative(root, path))
+          .filter((path) => !/^\.declapract\./.test(path))
+          .filter(
+            (path) =>
+              !/\.declapract\.(integration\.)?test\.ts(\.snap)?$/.test(path),
+          )
+          .map((path) => path.replace(/\.declapract\.ts$/, ''));
+        return [...new Set(paths)]
+          .sort()
+          .map((path) => ({ practice, purpose, root, path }));
+      }),
+    );
+
+/**
+ * .what = the label a report uses for one declaration
+ */
+const asDeclarationLabel = (input: Declaration): string => {
+  const where =
+    input.purpose === 'best-practice'
+      ? 'best-practice'
+      : `bad-practices/${relative(join(practicesDir, input.practice, 'bad-practices'), input.root)}`;
+  return `${input.practice} ${where}: ${input.path}`;
+};
+
+/**
+ * .what = the `.declapract.ts` module of a declaration, or null where it has none
+ */
+const getDeclarationModule = (
+  input: Declaration,
+): DeclarationModule | null => {
+  const modulePath = join(input.root, `${input.path}.declapract.ts`);
+  if (!existsSync(modulePath)) return null;
+  // require keeps the sweep synchronous, so one `then` reports every declaration at once
+  return require(modulePath) as DeclarationModule;
+};
+
+/**
+ * .what = the declared template contents, or null where the declaration ships none
+ */
+const getDeclaredContents = (input: Declaration): string | null => {
+  const templatePath = join(input.root, input.path);
+  if (!existsSync(templatePath)) return null;
+  return readFileSync(templatePath, 'utf8');
+};
+
+/**
+ * .what = the check type declapract assigns a declaration
+ */
+const getCheckType = (input: {
+  module: DeclarationModule | null;
+  contents: string | null;
+}): string => {
+  const check = input.module?.check;
+  const fallback = input.contents !== null ? 'EQUALS' : 'EXISTS';
+  if (check === undefined) return fallback;
+  if (typeof check === 'function') return 'CUSTOM';
+  if (typeof check === 'string') return check;
+  const declared = check as { type?: string; function?: unknown };
+  if (declared.function) return 'CUSTOM';
+  return declared.type ?? fallback;
+};
+
+/**
+ * .what = whether the declaration can fail with no fix that repairs a present file
+ * .note = mirrors declapract's getFileCheckDeclaration fix choice (see header)
+ */
+const isUnfixable = (input: Declaration): boolean => {
+  const module = getDeclarationModule(input);
+  if (typeof module?.fix === 'function') return false;
+  // an optional check passes on an absent file, so an EXISTS-optional check never fails
+  const declaredCheck = module?.check as { optional?: boolean } | undefined;
+  if (typeof declaredCheck === 'object' && declaredCheck?.optional === true)
+    return false;
+  const type = getCheckType({ module, contents: getDeclaredContents(input) });
+  if (input.purpose === 'bad-practice') return type !== 'EXISTS';
+  if (type === 'EQUALS') return false;
+  if (type === 'CONTAINS') return !input.path.endsWith('.json');
+  return true;
+};
+
+/**
+ * .what = the declarations that may fail with no fix, each with the reason the gap is kept
+ * .why  = each is a nudge that no fix can author (a file only the adopter can write, or a pattern
+ *         only the adopter can rewrite); a new gap must be added here, with its reason, or fixed
+ */
+const ADOPTER_AUTHORED_TEST =
+  'a nudge for a test only the adopter can author; no fix can write one';
+const ADOPTER_ACCOUNT_IDS =
+  'the right aws account id is known only to the adopter; a fix would guess it';
+const ADOPTER_EXCLUSIONS =
+  'CONTAINS over a file the adopter extends with its own entries; a rewrite would drop them';
+const UNFIXABLE_BY_DESIGN: Record<string, string> = {
+  'config bad-practices/configs-contain-wrong-account-id: config/prep.json':
+    ADOPTER_ACCOUNT_IDS,
+  'config bad-practices/configs-contain-wrong-account-id: config/prod.json':
+    ADOPTER_ACCOUNT_IDS,
+  'config bad-practices/configs-contain-wrong-account-id: config/test.json':
+    ADOPTER_ACCOUNT_IDS,
+  'config bad-practices/divergent-config-shapes: config/prep.json':
+    'the shared shape across prep and prod configs is a choice only the adopter can make',
+  'config bad-practices/divergent-config-shapes: config/prod.json':
+    'the shared shape across prep and prod configs is a choice only the adopter can make',
+  'dates-and-times bad-practices/moment: src/**/*.ts':
+    'a moment migration rewrites call sites by hand; a dropped import breaks the build, so the flag lands on the importer for the adopter to migrate to iso-time',
+  'directory-structure-src best-practice: src/contract/**/*.ts':
+    'a nudge for the layer dirs only the adopter can fill with code',
+  'directory-structure-src best-practice: src/domain.objects/**/*.ts':
+    'a nudge for the layer dirs only the adopter can fill with code',
+  'directory-structure-src best-practice: src/domain.operations/**/*.ts':
+    'a nudge for the layer dirs only the adopter can fill with code',
+  'domain best-practice: src/domain.objects/index.ts':
+    'a nudge for the domain objects only the adopter can author',
+  'persist-with-rds best-practice: provision/schema/sql/init.yml':
+    ADOPTER_EXCLUSIONS,
+  'tests-any best-practice: src/**/*.integration.test.ts': ADOPTER_AUTHORED_TEST,
+  'tests-any best-practice: src/**/*.test.ts': ADOPTER_AUTHORED_TEST,
+  'tests-any bad-practices/mocks: **/__mock__/*.js':
+    'a mock must be rewritten into a real seam by the adopter; a fix cannot',
+  'tests-any bad-practices/mocks: **/__mock__/*.ts':
+    'a mock must be rewritten into a real seam by the adopter; a fix cannot',
+  'tests-node best-practice: jest.unit.env.ts': ADOPTER_EXCLUSIONS,
+  'tests-service best-practice: blackbox/**/*.acceptance.test.ts':
+    ADOPTER_AUTHORED_TEST,
+  'tests-service best-practice: blackbox/lambdas/*.acceptance.test.ts':
+    ADOPTER_AUTHORED_TEST,
+  'tests-service best-practice: src/**/*.integration.test.ts':
+    ADOPTER_AUTHORED_TEST,
+  'tests-service best-practice: src/**/*.test.ts': ADOPTER_AUTHORED_TEST,
+};
+
+/**
+ * .what = swaps declapract's template expressions for plain values, as an adopter's apply would
+ */
+const asHydratedContents = (input: { contents: string }): string =>
+  input.contents
+    .replace(/@declapract\{check\.minVersion\('([^']+)'\)\}/g, '$1')
+    .replace(/@declapract\{variable\.[^}]+\}/g, 'demo');
+
+/**
+ * .what = the first line of a thrown value, for a one-line report
+ */
+const asFailureMessage = (error: unknown): string => {
+  if (typeof error === 'object' && error !== null && 'message' in error)
+    return String(error.message).split('\n')[0] ?? '';
+  return String(error);
+};
+
+/**
+ * .what = runs one fix twice over one input and reports how it fell short, if it did
+ */
+const getFixFailures = async (input: {
+  label: string;
+  purpose: Purpose;
+  fix: FixFn;
+  check: CheckFn | null;
+  contents: string | null;
+  context: Record<string, unknown>;
+}): Promise<string[]> => {
+  try {
+    const once = await input.fix(input.contents, input.context);
+    const onceContents =
+      once.contents === undefined ? input.contents : once.contents;
+    const twice = await input.fix(onceContents, input.context);
+    const twiceContents =
+      twice.contents === undefined ? onceContents : twice.contents;
+    const drift =
+      twiceContents === onceContents
+        ? []
+        : [`${input.label}: fix(fix(x)) !== fix(x)`];
+    // a fix may decline to author a file another practice owns (e.g. key order of package.json);
+    // the check is held to the output only where the fix wrote one
+    if (input.check && input.purpose === 'best-practice' && onceContents !== null)
+      await input.check(onceContents, input.context);
+    // a bad-practice check returns where it detects the pattern; on the fixed file it must throw,
+    // or every apply flags the file again and the fix never settles
+    const redetected =
+      input.check && input.purpose === 'bad-practice'
+        ? await getRedetection({
+            label: input.label,
+            check: input.check,
+            contents: onceContents,
+            context: input.context,
+          })
+        : [];
+    return [...drift, ...redetected];
+  } catch (error) {
+    return [`${input.label}: ${asFailureMessage(error)}`];
+  }
+};
+
+/**
+ * .what = reports a bad-practice check that still detects its pattern on the fixed file
+ * .why  = declapract reads ANY throw from a bad-practice check as "not detected", so this mirrors
+ *         the engine: a return is the redetection, and every throw is the settled state
+ */
+const getRedetection = async (input: {
+  label: string;
+  check: CheckFn;
+  contents: string | null;
+  context: Record<string, unknown>;
+}): Promise<string[]> => {
+  try {
+    await input.check(input.contents, input.context);
+    return [`${input.label}: the bad-practice check still detects on fix(x)`];
+  } catch {
+    return []; // the check threw: the pattern is gone
+  }
+};
+
+describe('every declaration has a fix that converges (#607, #536)', () => {
+  const declarations = getAllDeclarations();
+
+  given('[case0] every declaration in every practice', () => {
+    then('declarations of both purposes are found, so the sweep is not vacuous', () => {
+      const purposes = new Set(declarations.map(({ purpose }) => purpose));
+      expect([...purposes].sort()).toEqual(['bad-practice', 'best-practice']);
+    });
+  });
+
+  given('[case1] the fix of each declaration', () => {
+    when('[t0] the declarations with no fix are listed', () => {
+      const unfixable = declarations
+        .filter(isUnfixable)
+        .map(asDeclarationLabel);
+
+      then('each is on the allowlist, with its reason', () => {
+        expect(
+          unfixable.filter((label) => !(label in UNFIXABLE_BY_DESIGN)),
+        ).toEqual([]);
+      });
+
+      then('the allowlist names no declaration that has since gained a fix', () => {
+        expect(
+          Object.keys(UNFIXABLE_BY_DESIGN).filter(
+            (label) => !unfixable.includes(label),
+          ),
+        ).toEqual([]);
+      });
+    });
+  });
+
+  given('[case2] every declared custom fix', () => {
+    const projectRoot = genTempDir({ slug: 'practice-fix-coverage' });
+
+    when('[t0] each fix runs on the absent file and on its own template', () => {
+      then('check(fix(x)) settles and fix(fix(x)) === fix(x)', async () => {
+        const failures: string[] = [];
+        for (const declaration of declarations) {
+          const module = getDeclarationModule(declaration);
+          if (typeof module?.fix !== 'function') continue;
+          const template = getDeclaredContents(declaration);
+          const declaredFileContents =
+            template === null ? null : asHydratedContents({ contents: template });
+          const context = {
+            declaredFileContents,
+            relativeFilePath: declaration.path,
+            projectPractices: [declaration.practice],
+            projectVariables: {},
+            getProjectRootDirectory: () => projectRoot,
+          };
+          // a best-practice check must pass on the fixed file; a bad-practice check must throw on it
+          const check =
+            typeof module.check === 'function' ? (module.check as CheckFn) : null;
+          const inputs =
+            declaration.purpose === 'best-practice'
+              ? [null, declaredFileContents]
+              : [declaredFileContents];
+          for (const contents of inputs)
+            failures.push(
+              ...(await getFixFailures({
+                label: `${asDeclarationLabel(declaration)} (input: ${contents === null ? 'absent' : 'template'})`,
+                purpose: declaration.purpose,
+                fix: module.fix as FixFn,
+                check,
+                contents,
+                context,
+              })),
+            );
+        }
+        expect(failures).toEqual([]);
+      });
+    });
+  });
+});