declapract-typescript-ehmpathy 0.49.9 → 0.49.11

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.31.7`, 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.31.7"
+}

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

@@ -0,0 +1,15 @@
+import { FileCheckType } from 'declapract';
+
+/**
+ * .what = pins `packageManager` to an EXACT pnpm version (`pnpm@10.31.7`), 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.
+ * .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.1')}",
+    "declastruct-github": "@declapract{check.minVersion('1.7.2')}",
+    "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;

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

@@ -0,0 +1,229 @@
+import type { DeclastructProvider } from 'declastruct';
+import {
+  type DeclaredGithubBranch,
+  DeclaredGithubBranchProtection,
+  DeclaredGithubEnvironment,
+  type DeclaredGithubOrg,
+  DeclaredGithubRepo,
+  DeclaredGithubRepoConfig,
+  DeclaredGithubRepoRuleset,
+  type DeclaredGithubTeam,
+  DeclaredGithubTeamRepoAccess,
+  getDeclastructGithubProvider,
+} from 'declastruct-github';
+import { type DomainEntity, RefByUnique } from 'domain-objects';
+import { UnexpectedCodePathError } from 'helpful-errors';
+import { genLogMethods } from 'sdk-logs';
+
+import pkgJson from '../../package.json';
+
+const pkg = pkgJson as {
+  description?: string;
+  private?: boolean;
+  homepage?: string;
+};
+
+export const getProviders = async (): Promise<DeclastructProvider[]> => [
+  getDeclastructGithubProvider(
+    {
+      credentials: {
+        token:
+          process.env.GITHUB_TOKEN ??
+          UnexpectedCodePathError.throw('github token not supplied'),
+      },
+    },
+    {
+      // MUST be an sdk-logs logger — 1.6.0 DAOs read log._.level via as-procedure
+      log: genLogMethods(),
+    },
+  ),
+];
+
+export const getResources = async (): Promise<DomainEntity<any>[]> => {
+  // declare the repo
+  const repo = DeclaredGithubRepo.as({
+    owner: '@declapract{variable.organizationName}',
+    name: '@declapract{variable.projectName}',
+    description: pkg.description ?? null,
+    visibility: pkg.private === true ? 'private' : 'public',
+    private: pkg.private ?? false, // todo: why do we have to specify this twice?
+    homepage: pkg.homepage ?? null,
+
+    // things we haven't changed from the defaults
+    archived: false,
+  });
+
+  // ref the main branch
+  const branchMain = RefByUnique.as<typeof DeclaredGithubBranch>({
+    name: 'main',
+    repo,
+  });
+
+  // declare config for the repo
+  const repoConfig = DeclaredGithubRepoConfig.as({
+    repo,
+
+    // explicitly set the main branch
+    defaultBranch: branchMain.name,
+
+    // we only use issues; the rest is noise today
+    hasIssues: true,
+    hasProjects: false,
+    hasWiki: false,
+    isTemplate: false,
+
+    // only squash merges are allowed
+    allowSquashMerge: true,
+    allowMergeCommit: false, // but especially not merge merges. never merge merges
+    allowRebaseMerge: false,
+
+    // allow nice to haves for pulls
+    allowAutoMerge: true,
+    allowUpdateBranch: true,
+
+    // always cleanup after yourself
+    deleteBranchOnMerge: true,
+
+    // configure messages
+    mergeCommitMessage: 'PR_TITLE',
+    mergeCommitTitle: 'MERGE_MESSAGE',
+    squashMergeCommitMessage: 'COMMIT_MESSAGES',
+    squashMergeCommitTitle: 'COMMIT_OR_PR_TITLE',
+    webCommitSignoffRequired: false,
+  });
+
+  // declare protection for that branch, too
+  const branchMainProtection = DeclaredGithubBranchProtection.as({
+    branch: branchMain,
+
+    enforceAdmins: 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)
+    allowsDeletions: false, // dont allow the `main` branch to be deleted
+    allowsForcePushes: false, // dont allow `main` branch to be force pushed to
+    requireLinearHistory: false, //  # no ugly merge commits, woo! 🎉
+
+    requiredStatusChecks: {
+      strict: true, // branch must be up to date. otherwise, we dont know if it will really pass once it is merged
+      contexts: [
+        'suite / install / pnpm',
+        'suite / enshard',
+        '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",
+      ],
+    },
+
+    // things we haven't changed from the defaults
+    allowForkSyncing: false,
+    blockCreations: false,
+    lockBranch: false,
+    requiredConversationResolution: false,
+    requiredPullRequestReviews: null,
+    requiredSignatures: false,
+    restrictions: null,
+  });
+
+  // ref the releasers team
+  const teamReleasers = RefByUnique.as<typeof DeclaredGithubTeam>({
+    org: RefByUnique.as<typeof DeclaredGithubOrg>({ login: '@declapract{variable.organizationName}' }),
+    slug: 'releasers',
+  });
+
+  // grant the releasers team push access to the repo (standalone; no env depends on it)
+  const teamReleasersRepoAccess = DeclaredGithubTeamRepoAccess.as({
+    team: teamReleasers,
+    repo,
+    permission: 'push', // write access needed to deploy
+  });
+
+  // declare environment for production deployments from main (auto-approved)
+  const envProductionOnMain = DeclaredGithubEnvironment.as({
+    repo,
+    name: 'production-on-main',
+    reviewers: null, // no approval required — PR merge is the gate
+    waitTimer: null, // no delay
+    deploymentBranchPolicy: {
+      // accept both the main branch and `v*` release tags: prod deploys are
+      // triggered by a release tag cut from main (see protect-release-tags
+      // ruleset below), so the ref gate must admit that tag. a branch-only
+      // policy would have the environment reject the tag-triggered deploy.
+      // (requires declastruct-github >=1.7.2 for tag-target customPatterns.)
+      customPatterns: [
+        { name: 'main', target: 'branch' },
+        { name: 'v*', target: 'tag' },
+      ],
+    },
+    preventSelfReview: false,
+  });
+
+  // declare environment for adhoc production apply from a non-main branch
+  // .why = github env "required reviewers" is Enterprise-only; on a private repo
+  //        under the Free/Pro/Team plan the api returns 422 for BOTH team and user
+  //        reviewers. so this env carries NO protection rule — the human gate lives
+  //        in aws via an `actor_id` allowlist on this env's sts trust statement
+  //        (declared org-wide in aws.auth). do NOT add `reviewers` here (it will 422 on apply).
+  const envProductionOnElseApply = DeclaredGithubEnvironment.as({
+    repo,
+    name: 'production-on-else-apply',
+    reviewers: null, // gate is the aws actor_id allowlist, not a github reviewer
+    waitTimer: null,
+    deploymentBranchPolicy: null, // any branch
+    preventSelfReview: false,
+  });
+
+  // declare environment for production plan from any branch (readonly, no approval)
+  const envProductionOnElsePlan = DeclaredGithubEnvironment.as({
+    repo,
+    name: 'production-on-else-plan',
+    reviewers: null, // no approval required — plan is readonly, safe
+    waitTimer: null, // no delay
+    deploymentBranchPolicy: null, // any branch
+    preventSelfReview: false,
+  });
+
+  // restrict who may cut `v*` release tags to the rhelease app only
+  // .why = prod apply is gated on a release tag cut from main; if anyone could push a
+  //        `v*` tag, that gate is bypassable. this ruleset blocks create/move/delete of
+  //        `v*` tags for everyone except the rhelease app (the github half of the oidc guarantee)
+  const rulesetReleaseTags = DeclaredGithubRepoRuleset.as({
+    repo,
+    name: 'protect-release-tags',
+    target: 'tag',
+    enforcement: 'active',
+
+    // only the rhelease github app may create `v*` tags
+    bypassActors: [
+      {
+        actorId: 2472031, // rhelease github app id (gh api /apps/rhelease)
+        actorType: 'Integration',
+        bypassMode: 'always',
+      },
+    ],
+
+    // applies to release tags only
+    conditions: {
+      refNameInclude: ['refs/tags/v*'],
+      refNameExclude: [],
+    },
+
+    // enforce release-tag immutability: only the bypass actor may create, move, or delete
+    // matched tags. a released `v1.2.3` must never be re-pointed or removed once cut
+    rules: [{ type: 'creation' }, { type: 'update' }, { type: 'deletion' }],
+  });
+
+  // and return the full set
+  return [
+    repo,
+    repoConfig,
+    branchMainProtection,
+    teamReleasersRepoAccess,
+    envProductionOnMain,
+    envProductionOnElseApply,
+    envProductionOnElsePlan,
+    rulesetReleaseTags,
+  ];
+};

package/dist/.test/assets/expo-fullusecase/declarations/practices/rhachet/bad-practices/deprecated-use-file/.declapract.readme.md

@@ -0,0 +1,11 @@
+# Deprecated rhachet.use.ts File
+
+This bad practice detects and removes the deprecated `@/rhachet.use.ts` (i.e., `rhachet.use.ts` at repo root) config file.
+
+## Why
+
+The `rhachet.use.ts` config file pattern has been deprecated. Projects should migrate away from this pattern.
+
+## Fix
+
+The fix automatically deletes the file from the repository.

package/dist/.test/assets/expo-fullusecase/declarations/practices/rhachet/bad-practices/deprecated-use-file/rhachet.use.ts.declapract.ts

@@ -0,0 +1,12 @@
+import { FileCheckType, type FileFixFunction } from 'declapract';
+
+/**
+ * .what = detects the deprecated @/rhachet.use.ts config file
+ * .why = this config file pattern has been deprecated and should be removed
+ */
+
+export const check = FileCheckType.EXISTS;
+
+export const fix: FileFixFunction = () => {
+  return { contents: null }; // delete the file
+};