declapract-typescript-ehmpathy 0.49.10 → 0.49.12

package/dist/.test/assets/expo-fullusecase/declarations/practices/pnpm/bad-practices/package-lock-json/.declapract.readme.md

@@ -0,0 +1,30 @@
+# bad-practice: package-lock-json
+
+## .what
+
+a `package-lock.json` (the npm lockfile) in a repo that has migrated to pnpm.
+
+## .why it is bad
+
+pnpm reads `pnpm-lock.yaml`, not `package-lock.json`. a stale npm lockfile left beside the pnpm one
+is a dual source of truth for the dependency graph, and CI lockfile checks that grep the wrong file
+pass or fail for the wrong reason.
+
+## .the fix — forget-not-destroy
+
+the fix removes `package-lock.json`, but ONLY once a `pnpm-lock.yaml` sits beside it. the delete is
+gated on the pnpm lockfile's presence (read from the project root via
+`context.getProjectRootDirectory()`), so a fix that runs on a repo that has not yet run
+`pnpm install` is a no-op rather than a destructive strip that leaves the repo lockfile-less. this
+is the wish's stated safety bar: *"package-lock.json is removed ONLY after pnpm-lock.yaml exists, so
+a fix interrupted midway never leaves the repo lockfile-less."*
+
+a bare `FileCheckType.EXISTS` would delegate to declapract's default fix, which deletes the file
+UNCONDITIONALLY — so this practice declares its own gated `check`/`fix` instead.
+
+## .see also
+
+- `package-lock.json.declapract.integration.test.ts` — the forget-not-destroy clamp (delete-when-safe
+  + survive-when-unsafe)
+- `rule.require.clamp-edge-cases` — the regression clamp a destructive fix owes
+- `howto.craft-practice-migrations` — the forget-not-destroy migration shape

package/dist/.test/assets/expo-fullusecase/declarations/practices/pnpm/bad-practices/package-lock-json/package-lock.json.declapract.integration.test.ts

@@ -0,0 +1,105 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+import type { FileCheckContext } from 'declapract';
+import { given, then, useBeforeAll, when } from 'test-fns';
+
+import { check, fix } from './package-lock.json.declapract';
+
+/**
+ * .what = the forget-not-destroy clamp for the package-lock.json bad-practice.
+ * .why  = the fix DELETES the npm lockfile, so it is destructive — `rule.require.clamp-edge-cases`
+ *         demands a regression clamp that BITES. the gate reads the real filesystem for a
+ *         `pnpm-lock.yaml` beside the lockfile, so this is an integration test (a filesystem
+ *         boundary, per `rule.forbid.unit.remote-boundaries`), built on the `mkdtempSync`
+ *         throwaway-root pattern from `howto.craft-practice-migrations`. it proves BOTH paths:
+ *         delete-when-safe (pnpm-lock.yaml present) and skip-when-unsafe (absent) — the second
+ *         guards the forget-not-destroy contract: a bare EXISTS default-delete would fail it.
+ */
+/**
+ * .what = builds the minimal FileCheckContext the check and fix functions actually use
+ * .why  = declapract's FileCheckContext carries many fields the package-lock check/fix never
+ *         touch — they read only `getProjectRootDirectory()` (to look for a `pnpm-lock.yaml`
+ *         beside the lockfile). the single documented cast here is the sanctioned test-context
+ *         idiom (howto.craft-practice-migrations); it is confined to this helper so no call
+ *         site casts. removal path: drop the cast the day declapract exports a partial-context
+ *         builder.
+ */
+const genContextForRoot = (root: string): FileCheckContext =>
+  ({ getProjectRootDirectory: () => root }) as unknown as FileCheckContext;
+
+describe('pnpm package-lock-json — forget-not-destroy gate', () => {
+  // .note = deliberate mutation — `roots` accumulates every temp dir genRoot mints so the
+  //         afterAll below can remove them all; a scoped, single-threaded test-cleanup zone
+  //         (rule.require.immutable-vars sanctions in-place mutation with this note).
+  const roots: string[] = [];
+  const genRoot = (slug: string, files: Record<string, string>): string => {
+    const root = mkdtempSync(path.join(tmpdir(), `pnpm-lock-${slug}-`));
+    for (const [name, body] of Object.entries(files))
+      writeFileSync(path.join(root, name), body);
+    roots.push(root);
+    return root;
+  };
+
+  afterAll(() => {
+    for (const root of roots) rmSync(root, { recursive: true, force: true });
+  });
+
+  given('[case1] a package-lock.json WITH a pnpm-lock.yaml beside it', () => {
+    const state = useBeforeAll(async () => {
+      const root = genRoot('safe', {
+        'package-lock.json': '{}',
+        'pnpm-lock.yaml': 'lockfileVersion: 9\n',
+      });
+      const context = genContextForRoot(root);
+      return { context, fixed: (await fix('{}', context)).contents };
+    });
+
+    when('[t0] the bad-practice is evaluated', () => {
+      then('check detects it — safe to remove', () => {
+        expect(() => check('{}', state.context)).not.toThrow();
+      });
+
+      then('fix removes it — contents become null', () => {
+        expect(state.fixed).toBeNull();
+      });
+    });
+  });
+
+  given('[case2] a package-lock.json with NO pnpm-lock.yaml beside it', () => {
+    const state = useBeforeAll(async () => {
+      const root = genRoot('unsafe', { 'package-lock.json': '{}' });
+      const context = genContextForRoot(root);
+      return { context, fixed: (await fix('{}', context)).contents };
+    });
+
+    when('[t0] the bad-practice is evaluated', () => {
+      then('check skips it — forget-not-destroy, no pnpm-lock.yaml yet', () => {
+        expect(() => check('{}', state.context)).toThrow(
+          'does not match bad practice',
+        );
+      });
+
+      then('fix is a no-op — the npm lockfile is preserved', () => {
+        // a bare EXISTS default-delete would make this null, which this test would catch
+        expect(state.fixed).toEqual('{}');
+      });
+    });
+  });
+
+  given('[case3] no package-lock.json at all', () => {
+    const state = useBeforeAll(async () => {
+      const root = genRoot('absent', { 'pnpm-lock.yaml': 'lockfileVersion: 9\n' });
+      return { context: genContextForRoot(root) };
+    });
+
+    when('[t0] the bad-practice is evaluated', () => {
+      then('check skips it — no npm lockfile to remove', () => {
+        expect(() => check(null, state.context)).toThrow(
+          'does not match bad practice',
+        );
+      });
+    });
+  });
+});

package/dist/.test/assets/expo-fullusecase/declarations/practices/pnpm/bad-practices/package-lock-json/package-lock.json.declapract.ts

@@ -0,0 +1,41 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+
+/**
+ * .what = detects a `package-lock.json` (the npm lockfile) that is SAFE to remove — i.e. only
+ *         once a `pnpm-lock.yaml` sits beside it.
+ * .why  = the npm→pnpm migration must be FORGET-NOT-DESTROY: `package-lock.json` is removed ONLY
+ *         after `pnpm-lock.yaml` exists, so a fix interrupted midway never leaves the repo
+ *         lockfile-less (the wish's stated safety bar). a bare `FileCheckType.EXISTS` would let
+ *         declapract's default fix delete the npm lockfile UNCONDITIONALLY — even on a repo that
+ *         has not yet run `pnpm install` — which is exactly the destructive strip this gate
+ *         forecloses. so the delete is gated on the pnpm lockfile's presence, read from the
+ *         project root via `context.getProjectRootDirectory()`.
+ */
+const hasPnpmLock = (context: {
+  getProjectRootDirectory: () => string;
+}): boolean =>
+  existsSync(path.join(context.getProjectRootDirectory(), 'pnpm-lock.yaml'));
+
+export const check: FileCheckFunction = (contents, context) => {
+  // no package-lock.json → no npm lockfile to remove, skip
+  if (contents === null) throw new Error('does not match bad practice');
+
+  // forget-not-destroy: without a pnpm-lock.yaml beside it, removal would leave the repo
+  // lockfile-less — so this is NOT yet a safe-to-remove npm lockfile, skip
+  if (!hasPnpmLock(context)) throw new Error('does not match bad practice');
+
+  // package-lock.json present AND pnpm-lock.yaml present → safe to remove, detected
+  return;
+};
+
+export const fix: FileFixFunction = (contents, context) => {
+  // gate the delete on the pnpm lockfile's presence (forget-not-destroy) — a fix that ran
+  // where the check would not detect leaves the file untouched, never lockfile-less
+  if (!hasPnpmLock(context)) return { contents };
+
+  // pnpm-lock.yaml exists → remove the redundant npm lockfile
+  return { contents: null };
+};

package/dist/.test/assets/expo-fullusecase/declarations/practices/pnpm/best-practice/.declapract.readme.md

@@ -0,0 +1,22 @@
+# pnpm best-practice — what this practice owns, and what it does NOT
+
+this practice owns the pnpm **adoption** signal: the `packageManager` exact pin
+(`pnpm@10.34.5`, an intentional org-convergence requirement — see the `.declapract.ts` note).
+
+## where the hoisted-linker `.npmrc` lives — NOT here
+
+the pnpm-only `.npmrc` directives an expo repo needs (`node-linker=hoisted`,
+`public-hoist-pattern[]=*expo*`, …) are declared by the **`node`** practice, not this one. the
+`node` practice owns the whole `.npmrc` (it is the package-manager-config file), and its declaration
+is usecase-aware: it findserts the hoist block only when the `cicd-app-react-native-expo` usecase is
+present.
+
+so an auditor of all that pnpm needs should also read:
+
+- `src/practices/node/best-practice/.npmrc.declapract.ts` — the usecase-aware `.npmrc` declaration
+- `src/utils/defineExpectedNpmrcContents.ts` — the shared base + expo-hoist line source
+- `.agent/repo=.this/role=any/briefs/howto.pnpm-expo-hoisted-linker.md` — why the flat linker is
+  required for metro/expo, and the transitive-skew gotcha it exposes
+
+the split is deliberate: the `.npmrc` is one file with one owner (`node`), so a repo gets a single
+coherent `.npmrc` rather than two practices that fight over it.

package/dist/.test/assets/expo-fullusecase/declarations/practices/pnpm/best-practice/package.json

@@ -0,0 +1,3 @@
+{
+  "packageManager": "pnpm@10.34.5"
+}

package/dist/.test/assets/expo-fullusecase/declarations/practices/pnpm/best-practice/package.json.declapract.ts

@@ -0,0 +1,17 @@
+import { FileCheckType } from 'declapract';
+
+/**
+ * .what = pins `packageManager` to an EXACT pnpm version (`pnpm@10.34.5`), not a minVersion.
+ * .why  = this is an intentional org-standardization REQUIREMENT, not an oversight. every pnpm
+ *         consumer runs ONE blessed pnpm version, so `corepack` / `pnpm/action-setup@v4` load the
+ *         identical toolchain across CI, local, and every repo — reproducible installs, no per-repo
+ *         drift. an exact pin is also the ONLY correct shape here: the `packageManager` field is a
+ *         corepack spec that requires the `pnpm@<version>` prefix, which declapract's bare-semver
+ *         `check.minVersion(..)` cannot emit. the pin's major stays v10 by hard rule — see
+ *         `.agent/repo=.this/role=any/briefs/rule.require.pnpm-major-v10.md` (v11 inverts the
+ *         build-allowlist model the peer practices encode).
+ * .note = a consumer ahead of the pin (e.g. on 10.32.1) is pinned BACK to the blessed version on
+ *         `declapract fix` — that convergence-to-one-version is the intent, not a regression. when
+ *         the org bumps the blessed version, this pin bumps and every consumer follows.
+ */
+export const check = FileCheckType.CONTAINS;

package/dist/.test/assets/expo-fullusecase/declarations/practices/provision-github/bad-practices/deprecated-reviewers-variable/declapract.use.yml.declapract.ts

@@ -0,0 +1,41 @@
+import type { FileCheckFunction, FileFixFunction } from 'declapract';
+import yaml from 'yaml';
+
+/**
+ * .what = removes deprecated reviewers.users variable from declapract.use.yml
+ * .why = production-on-else environment now uses team:releaser instead of user list
+ */
+
+export const check: FileCheckFunction = (contents) => {
+  if (!contents) throw new Error('no file found');
+
+  const parsed = yaml.parse(contents) as {
+    variables?: Record<string, unknown>;
+  };
+  const variables = parsed?.variables ?? {};
+
+  // check if reviewers or reviewers.users exists
+  if ('reviewers' in variables) return; // bad practice detected
+
+  throw new Error('no deprecated reviewers variable found');
+};
+
+export const fix: FileFixFunction = (contents) => {
+  if (!contents) return { contents };
+
+  // parse with parseDocument to preserve comments and format
+  const doc = yaml.parseDocument(contents);
+  const parsed = doc.toJSON() as { variables?: Record<string, unknown> };
+
+  if (!parsed?.variables || !('reviewers' in parsed.variables)) {
+    return { contents };
+  }
+
+  // remove the reviewers key from variables
+  const variablesNode = doc.get('variables') as yaml.YAMLMap | undefined;
+  if (variablesNode) {
+    variablesNode.delete('reviewers');
+  }
+
+  return { contents: doc.toString() };
+};

package/dist/.test/assets/expo-fullusecase/declarations/practices/provision-github/bad-practices/old-declastruct-resources-path/provision/github/declastruct.resources.ts.declapract.ts

@@ -0,0 +1,7 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.EXISTS;
+
+export const fix: FileFixFunction = () => {
+  return { contents: null }; // delete old path, replaced by provision/github.repo/resources.ts
+};

package/dist/.test/assets/expo-fullusecase/declarations/practices/provision-github/bad-practices/terraform-github/provision/github/environment/import-existing-repo.sh

@@ -0,0 +1,12 @@
+# terraform... why cant you just look this stuff up given that you already have the inputs....
+REPO_NAME='@declapract{variable.projectName}';
+
+# import the repo itself
+terraform import module.product.github_repository.this $REPO_NAME;
+
+# import the default branch setting
+terraform import module.product.github_branch_default.default_branch_is_main $REPO_NAME;
+
+# import the branch protection rules
+terraform import "module.product.github_branch_protection.main_branch[0]" $REPO_NAME:main
+

package/dist/.test/assets/expo-fullusecase/declarations/practices/provision-github/bad-practices/terraform-github/provision/github/environment/import-existing-repo.sh.declapract.ts

@@ -0,0 +1,3 @@
+import { FileCheckType } from 'declapract';
+
+export const check = FileCheckType.EXISTS;

package/dist/.test/assets/expo-fullusecase/declarations/practices/provision-github/bad-practices/terraform-github/provision/github/environment/main.tf

@@ -0,0 +1,20 @@
+provider "github" {
+  owner = "@declapract{variable.organizationName}" # for the @declapract{variable.organizationName} organization
+  # note: `token` is sourced from env var GITHUB_TOKEN (e.g,. `use.github`)
+}
+
+terraform {
+  backend "s3" {
+    bucket  = "terraform-state-xdeclapract{variable.infrastructureNamespaceId}-prod" # tracked in the prod aws account's s3 bucket, so `use.@declapract{variable.organizationName}.prod`
+    key     = "@declapract{variable.projectName}-github"
+    region  = "us-east-1"
+    encrypt = true
+  }
+}
+
+module "product" {
+  source     = "../product"
+  name       = "@declapract{variable.projectName}"
+  visibility = "private"
+  protected  = true
+}

package/dist/.test/assets/expo-fullusecase/declarations/practices/provision-github/bad-practices/terraform-github/provision/github/environment/main.tf.declapract.ts

@@ -0,0 +1,3 @@
+import { FileCheckType } from 'declapract';
+
+export const check = FileCheckType.EXISTS;

package/dist/.test/assets/expo-fullusecase/declarations/practices/provision-github/bad-practices/terraform-github/provision/github/environment/versions.tf

@@ -0,0 +1,9 @@
+terraform {
+  required_version = ">= 0.14"
+  required_providers {
+    github = {
+      source  = "hashicorp/github"
+      version = "~> 4.19.1"
+    }
+  }
+}

package/dist/.test/assets/expo-fullusecase/declarations/practices/provision-github/bad-practices/terraform-github/provision/github/environment/versions.tf.declapract.ts

@@ -0,0 +1,3 @@
+import { FileCheckType } from 'declapract';
+
+export const check = FileCheckType.EXISTS;

package/dist/.test/assets/expo-fullusecase/declarations/practices/provision-github/bad-practices/terraform-github/provision/github/product/repository.tf

@@ -0,0 +1,74 @@
+variable "name" {
+  type = string
+}
+variable "visibility" {
+  default = "private"
+}
+variable "protected" {
+  default = true
+}
+
+# the repository itself
+resource "github_repository" "this" {
+  name       = var.name
+  visibility = var.visibility
+
+  # standard settings
+  has_issues             = true # only issues are allowed... todo: decide if there's too much overlap between linear and issues
+  has_projects           = false
+  has_wiki               = false
+  has_downloads          = false
+  is_template            = false
+  allow_squash_merge     = true  # only squash merges are allowed
+  allow_merge_commit     = false # especially not merge merges. never merge merges
+  allow_rebase_merge     = false
+  allow_auto_merge       = true
+  delete_branch_on_merge = true # always delete branch on merging
+
+  lifecycle {
+    ignore_changes = [
+      description, # dont worry about the description in these checks; the purpose of these checks is to check developer experience, not repo contents
+      homepage_url # dont worry about the homepay-url in these checks either; same as above
+    ]
+  }
+}
+
+# the main branch (its "data" instead of a "resource" because 1. you cant create it w/ terraform anyway, 2. there's a constant "etag" out of sync with terraform)
+data "github_branch" "main" {
+  repository = github_repository.this.name
+  branch     = "main"
+}
+
+# set it as the default for this org
+resource "github_branch_default" "default_branch_is_main" {
+  repository = github_repository.this.name
+  branch     = data.github_branch.main.branch
+}
+
+# the branch protection rule on the main branch
+resource "github_branch_protection" "main_branch" {
+  repository_id = github_repository.this.node_id
+  pattern       = data.github_branch.main.branch
+
+  enforce_admins          = true  # yes, even admins need to follow this (note: they can still take the time to go and change the settings temporarily for the exceptions)
+  allows_deletions        = false # dont allow the `main` branch to be deleted
+  allows_force_pushes     = false # dont allow `main` branch to be force pushed to
+  required_linear_history = true  # no ugly merge commits, woo! 🎉
+
+  required_status_checks {
+    strict = true # branch must be up to date. otherwise, we dont know if it will really pass once it is merged
+    contexts = [
+      "suite / install / npm",
+      "suite / test-commits",
+      "suite / test-types",
+      "suite / test-format",
+      "suite / test-lint",
+      "suite / test-unit",
+      "suite / test-integration",
+      "suite / test-acceptance-locally",
+      "pullreq-title" # "review / pullreq-title",
+    ]
+  }
+
+  count = var.protected == false ? 0 : 1 # only define protection rules if this repository is marked as protected (default = true)
+}

package/dist/.test/assets/expo-fullusecase/declarations/practices/provision-github/bad-practices/terraform-github/provision/github/product/repository.tf.declapract.ts

@@ -0,0 +1,3 @@
+import { FileCheckType } from 'declapract';
+
+export const check = FileCheckType.EXISTS;

package/dist/.test/assets/expo-fullusecase/declarations/practices/provision-github/best-practice/.declapract.readme.md

@@ -0,0 +1,7 @@
+provisions github repository settings and environments via declastruct-github-sdk.
+
+## required variables
+
+| variable | description | example |
+|----------|-------------|---------|
+| `reviewers.users` | github usernames for production deployment reviewers | `['whodisio', 'ehmpathy']` |

package/dist/.test/assets/expo-fullusecase/declarations/practices/provision-github/best-practice/package.json

@@ -0,0 +1,7 @@
+{
+  "devDependencies": {
+    "declastruct": "@declapract{check.minVersion('1.9.2')}",
+    "declastruct-github": "@declapract{check.minVersion('1.8.0')}",
+    "sdk-logs": "@declapract{check.minVersion('0.9.2')}"
+  }
+}

package/dist/.test/assets/expo-fullusecase/declarations/practices/provision-github/best-practice/package.json.declapract.ts

@@ -0,0 +1,3 @@
+import { FileCheckType } from 'declapract';
+
+export const check = FileCheckType.CONTAINS;