declapract-typescript-ehmpathy 0.49.11 → 0.49.13

package/dist/practices/environments/bad-practices/old-stage-enum/src/<star><star>/<star>.ts.declapract.ts

@@ -1,37 +1,304 @@
 import type { FileCheckFunction, FileFixFunction } from 'declapract';
+import * as ts from 'typescript';
+
+// `Stage.DEVELOPMENT` (value `'dev'`) was overloaded across two axes: the access
+// (→ 'prep') and the deploy-stage slug (→ 'dev'). a rewrite cannot know which axis a given
+// occurrence sits on. so the fix NEVER guesses it: `Stage.PRODUCTION` and `Stage.TEST` are
+// unambiguous and migrate to `'prod'` / `'test'`, but `Stage.DEVELOPMENT` is LEFT IN PLACE.
+// because it is left, `check` still detects it, so `declapract plan` stays RED until a
+// human decides the axis by hand — the loud, plan-visible "leave the file in violation"
+// signal guard #3 demands, never a green plan that hides a possibly-wrong `'prep'` guess.
+//
+// a red plan alone does not say WHERE the unsettled reference sits or WHAT the human must
+// do, so the fix also inserts a `// @declapract:review:` COMMENT directly above each
+// `Stage.DEVELOPMENT` line. the comment names the file location (it rides the very line) and
+// the choice to make (an access, or the deploy-stage slug). it is a COMMENT, not a value
+// splice — the real `Stage.DEVELOPMENT` property access is untouched — so it neither guesses a
+// value NOR clears the check (a comment is not a property-access node, so the parser still
+// detects the real reference and `plan` stays red). idempotent: a line that already holds the
+// marker is skipped, so a second `fix` pass adds no second marker.
+//
+// this pairs with, and is deliberately UNLIKE, an earlier shape that rewrote
+// `Stage.DEVELOPMENT` → `'prep' /* marker */`. that VALUE-SPLICE shape (a) still GUESSED
+// `'prep'` (a deploy-stage occurrence, whose correct value is `'dev'`, was silently
+// mis-migrated), and (b) once it rewrote the reference, the check no longer matched, so `plan`
+// read CLEAN with a possibly-wrong value — the exact silent-break class this wish exists to
+// retire. the COMMENT marker forecloses both: no value is emitted (no guess), and the
+// still-red plan cannot hide the unsettled axis — it now carries the pointer + the hint.
+
+/**
+ * .what = find every `Stage.<member>` reference in real code, via the typescript parser. three
+ *         node shapes carry it: a value-position PROPERTY ACCESS (`Stage.PRODUCTION`), a
+ *         type-position QUALIFIED NAME (`x: Stage.PRODUCTION`), and a bracket ELEMENT ACCESS with a
+ *         string-literal key (`Stage['PRODUCTION']`). all three name the same enum member and must
+ *         migrate together.
+ * .why  = the parser classifies every token exactly, so a `Stage.PRODUCTION` that sits inside a
+ *         comment, a string literal, a template literal's static text, or a REGEX literal is that
+ *         token's own text — never one of these three nodes — and is therefore invisible to this
+ *         walk BY CONSTRUCTION. a live `${Stage.X}` interpolation, by contrast, IS a property
+ *         access and is found. this forecloses the whole "a value spliced into a non-code span"
+ *         corruption class that a hand-rolled character mask could only chase one token position
+ *         at a time — a `/` after `}`/`)`/`]`, a regex nested in a `${...}`, a brace inside an
+ *         interpolated string — each a fresh hole. the parser has none. and the type + bracket
+ *         positions close the mirror hole: a `Stage.DEVELOPMENT` in a type annotation or a
+ *         `Stage['DEVELOPMENT']` bracket lookup is just as axis-ambiguous as the value form, so it
+ *         too must keep `check` red until a human settles it.
+ * .note = a `Stage.X` is matched wherever the top-level identifier `Stage` is accessed. a consumer
+ *         that shadows the enum with its own object literally named `Stage` is an accepted,
+ *         disclosed residual — the org-standard enum name is not re-used locally in practice.
+ */
+type StageAccess = { member: string; start: number; end: number };
+
+const getStageAccesses = (contents: string): StageAccess[] => {
+  const source = ts.createSourceFile(
+    'stage-scan.ts',
+    contents,
+    ts.ScriptTarget.Latest,
+    true, // setParentNodes — so getStart(source) reads real offsets
+    ts.ScriptKind.TS,
+  );
+  const accesses: StageAccess[] = [];
+  const visit = (node: ts.Node): void => {
+    // value position: `Stage.PRODUCTION`
+    if (
+      ts.isPropertyAccessExpression(node) &&
+      ts.isIdentifier(node.expression) &&
+      node.expression.text === 'Stage'
+    )
+      accesses.push({
+        member: node.name.text,
+        start: node.getStart(source),
+        end: node.getEnd(),
+      });
+
+    // type position: `x: Stage.PRODUCTION` (a QualifiedName, `left.right`)
+    if (
+      ts.isQualifiedName(node) &&
+      ts.isIdentifier(node.left) &&
+      node.left.text === 'Stage'
+    )
+      accesses.push({
+        member: node.right.text,
+        start: node.getStart(source),
+        end: node.getEnd(),
+      });
+
+    // bracket position: `Stage['PRODUCTION']` (an ElementAccess with a string-literal key)
+    if (
+      ts.isElementAccessExpression(node) &&
+      ts.isIdentifier(node.expression) &&
+      node.expression.text === 'Stage' &&
+      ts.isStringLiteral(node.argumentExpression)
+    )
+      accesses.push({
+        member: node.argumentExpression.text,
+        start: node.getStart(source),
+        end: node.getEnd(),
+      });
+
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+  return accesses;
+};
+
+// only PRODUCTION + TEST are unambiguous (prod → 'prod', test → 'test'). DEVELOPMENT is
+// axis-ambiguous and is deliberately NOT mapped here — it is never rewritten.
+const replacementFor = (member: string): string =>
+  member === 'PRODUCTION' ? "'prod'" : "'test'";
+
+/**
+ * .what = replace every unambiguous `Stage.PRODUCTION`/`Stage.TEST` PROPERTY ACCESS with its
+ *         string literal, spliced into the ORIGINAL at the parser's node offsets — so a comment,
+ *         string, template-static, or regex mention is preserved byte-for-byte (it is not a
+ *         property-access node, so it is never in the splice set). `Stage.DEVELOPMENT` is never in
+ *         the set, so it is left in place (never guessed).
+ * .why  = keeps `fix` a what-not-how read; the splice + offset math lives in this one op.
+ */
+const withUnambiguousStageRefsReplaced = (input: {
+  contents: string;
+}): string => {
+  const accesses = getStageAccesses(input.contents)
+    .filter(
+      (access) => access.member === 'PRODUCTION' || access.member === 'TEST',
+    )
+    .sort((a, b) => a.start - b.start);
+  // a pure fold over the sorted accesses — carries { spliced, last } with no mutable accumulator
+  // (rule.forbid.maintenance-hazards). each step appends the gap since the prior splice plus this
+  // member's literal, then advances the cursor past the property access.
+  const { spliced, last } = accesses.reduce(
+    (acc, access) => ({
+      spliced:
+        acc.spliced +
+        input.contents.slice(acc.last, access.start) +
+        replacementFor(access.member),
+      last: access.end,
+    }),
+    { spliced: '', last: 0 },
+  );
+  return spliced + input.contents.slice(last);
+};
+
+/**
+ * .what = drop the now-unused `Stage` named-import specifier — ONLY when no real-code `Stage.`
+ *         reference remains. done via the parser, so the `Stage` specifier is dropped wherever it
+ *         sits in the named-bindings list — first (`{ Stage, A }`), last (`{ A, Stage }`), or MIDDLE
+ *         (`{ A, Stage, B }`) — and the surviving specifiers are preserved verbatim. when `Stage`
+ *         is the sole specifier, the whole import statement (and its trailing newline) is removed.
+ * .why  = a leftover `Stage.DEVELOPMENT` still needs the import to compile, so the import is kept
+ *         while any real reference survives; keeps `fix` a what-not-how read. the parser finds the
+ *         specifier by its position in the list, so a mid-list `Stage` — which a first/last-only
+ *         regex silently skips, leaving a dead import that fails the lint — is dropped like any
+ *         other. a comment/string mention of `Stage` is not an import specifier, so it is untouched.
+ */
+const withUnusedStageImportRemoved = (input: { contents: string }): string => {
+  if (getStageAccesses(input.contents).length > 0) return input.contents;
+
+  const source = ts.createSourceFile(
+    'stage-import-scan.ts',
+    input.contents,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TS,
+  );
+
+  // find the `Stage` named-import specifier + the NamedImports list it sits in, via the parser
+  const found = source.statements.reduce<{
+    named: ts.NamedImports;
+    decl: ts.ImportDeclaration;
+  } | null>((hit, statement) => {
+    if (hit) return hit;
+    if (!ts.isImportDeclaration(statement)) return null;
+    const bindings = statement.importClause?.namedBindings;
+    if (!bindings || !ts.isNamedImports(bindings)) return null;
+    const hasStage = bindings.elements.some(
+      (specifier) => specifier.name.text === 'Stage',
+    );
+    return hasStage ? { named: bindings, decl: statement } : null;
+  }, null);
+
+  // no `Stage` specifier to drop → leave the file byte-for-byte
+  if (!found) return input.contents;
+
+  // the survivors — every specifier that is not `Stage`, kept verbatim by their source text
+  const survivors = found.named.elements.filter(
+    (specifier) => specifier.name.text !== 'Stage',
+  );
+
+  // sole specifier → remove the whole import statement, including its trailing newline
+  if (survivors.length === 0) {
+    const declStart = found.decl.getStart(source);
+    const declEnd = found.decl.getEnd();
+    const withTrailingNewline =
+      input.contents[declEnd] === '\n' ? declEnd + 1 : declEnd;
+    return (
+      input.contents.slice(0, declStart) +
+      input.contents.slice(withTrailingNewline)
+    );
+  }
+
+  // otherwise, rebuild the named-bindings list from the survivors + splice it over the original
+  const rebuilt = `{ ${survivors
+    .map((specifier) => specifier.getText(source))
+    .join(', ')} }`;
+  return (
+    input.contents.slice(0, found.named.getStart(source)) +
+    rebuilt +
+    input.contents.slice(found.named.getEnd())
+  );
+};
+
+// the review pointer inserted above each axis-ambiguous `Stage.DEVELOPMENT` line. it names WHERE
+// (it rides the reference's line) and WHAT (pick an access, or the deploy-stage slug). the
+// literal `Stage.DEVELOPMENT` text here sits in a `//` comment, so the parser never reads it as a
+// property access — it never keeps the check red on its own, and it never adds a second real ref.
+const REVIEW_MARKER =
+  "// @declapract:review: Stage.DEVELOPMENT is axis-ambiguous — pick by hand: an access ('test'|'prep'|'prod') or the deploy-stage slug ('dev'), then delete this marker";
+
+/**
+ * .what = insert a `// @declapract:review:` comment above each `Stage.DEVELOPMENT` line, once.
+ * .why  = the fix leaves `Stage.DEVELOPMENT` in place so `plan` stays red (guard #3), but a bare
+ *         red plan names neither the file/line nor the axis to pick. the comment supplies both,
+ *         without a value guess and without a cleared check (a comment is not a property access).
+ *         each line is marked at most once (idempotent), so a re-apply is a no-op.
+ */
+const withDevelopmentAxisReviewMarker = (input: {
+  contents: string;
+}): string => {
+  // the start offset of every line that holds a real `Stage.DEVELOPMENT` property access
+  const lineStarts = Array.from(
+    new Set(
+      getStageAccesses(input.contents)
+        .filter((access) => access.member === 'DEVELOPMENT')
+        .map(
+          (access) => input.contents.lastIndexOf('\n', access.start - 1) + 1,
+        ),
+    ),
+  ).sort((a, b) => b - a); // splice bottom-up so lower offsets stay valid
+
+  // a pure fold over the bottom-up line starts — carries the text-so-far with no mutable
+  // accumulator (rule.forbid.maintenance-hazards). each step splices the marker above its line, or
+  // returns the text unchanged when the contiguous comment block just above already holds the
+  // marker (idempotent).
+  return lineStarts.reduce((out, lineStart) => {
+    const indent = out.slice(lineStart).match(/^[ \t]*/)?.[0] ?? '';
+
+    // idempotent guard: walk up the CONTIGUOUS `//` comment block directly above this line and skip
+    // if any of its lines already holds the marker. a single-line check above would miss a marker
+    // that a reformat pushed one line up (e.g. a blank-less comment now sits between it and the
+    // reference), so it would double-insert. the block scan sees the whole comment run.
+    const priorBlockHoldsMarker = (() => {
+      const walk = (cursor: number): boolean => {
+        if (cursor === 0) return false;
+        const priorStart = out.lastIndexOf('\n', cursor - 2) + 1;
+        const priorLine = out.slice(priorStart, cursor - 1);
+        if (priorLine.includes('@declapract:review')) return true;
+        // stop at the first non-comment line — the comment block ends there
+        if (!priorLine.trimStart().startsWith('//')) return false;
+        return walk(priorStart);
+      };
+      return walk(lineStart);
+    })();
+    if (priorBlockHoldsMarker) return out;
+
+    return (
+      out.slice(0, lineStart) +
+      indent +
+      REVIEW_MARKER +
+      '\n' +
+      out.slice(lineStart)
+    );
+  }, input.contents);
+};
 
 export const check: FileCheckFunction = (contents) => {
-  if (!contents) throw new Error('does not match bad practice');
+  if (!contents)
+    throw new Error(
+      'does not match bad practice: file has no contents to scan for a Stage.* enum reference',
+    );
 
-  // check for Stage enum usage
-  if (
-    contents.includes('Stage.PRODUCTION') ||
-    contents.includes('Stage.DEVELOPMENT') ||
-    contents.includes('Stage.TEST')
-  )
-    return; // bad practice detected
+  // detect a `Stage.<member>` PROPERTY ACCESS in real code, via the parser. a comment/string/
+  // regex/template-static mention is not a property-access node, so it never keeps the check red
+  // after the fix (it would never clear). the check detects ALL three members — a DEVELOPMENT
+  // reference must keep the check red so `plan` stays visibly unsettled.
+  const accesses = getStageAccesses(contents);
+  if (accesses.length > 0) return; // bad practice detected
 
-  throw new Error('does not match bad practice');
+  throw new Error(
+    'does not match bad practice: no Stage.PRODUCTION|DEVELOPMENT|TEST property access found in real code (a comment/string/regex/template-static mention is ignored)',
+  );
 };
 
 export const fix: FileFixFunction = (contents) => {
   if (!contents) return { contents };
 
-  const fixed = contents
-    // replace enum values with string literals
-    .replace(/Stage\.PRODUCTION/g, "'prod'")
-    .replace(/Stage\.DEVELOPMENT/g, "'prep'")
-    .replace(/Stage\.TEST/g, "'test'")
-    // remove Stage import if no longer used
-    .replace(/import\s*\{\s*Stage\s*\}\s*from\s*['"][^'"]+['"];\n?/g, '')
-    .replace(
-      /import\s*\{\s*([^}]*),\s*Stage\s*\}\s*from/g,
-      'import { $1 } from',
-    )
-    .replace(
-      /import\s*\{\s*Stage\s*,\s*([^}]*)\}\s*from/g,
-      'import { $1 } from',
-    );
+  // migrate the unambiguous members, mark each axis-ambiguous `Stage.DEVELOPMENT` with a review
+  // pointer, then drop the Stage import when no reference remains. `Stage.DEVELOPMENT` is left in
+  // place (never guessed), so `check` still detects it and `plan` stays red until a human decides
+  // the axis — now with a `// @declapract:review:` line naming where + what.
+  const spliced = withUnambiguousStageRefsReplaced({ contents });
+  const marked = withDevelopmentAxisReviewMarker({ contents: spliced });
+  const fixed = withUnusedStageImportRemoved({ contents: marked });
 
   return { contents: fixed };
 };

package/dist/practices/environments/best-practice/.declapract.readme.md

@@ -1,22 +1,20 @@
 # environments
 
-a critical part of an application's environment is which stage it is running in
+a critical part of an application's environment is its `access` — which deployment's resources
+the runtime may reach, and with what weight.
 
-ehmpathy recognizes three standard stages in which applications run throughout their development cycle
-- `prod` stage - a deployed production stack in which application that the business depends on run, affecting real customers
-- `prep` stage - a deployed pre-production stack in which applications can run and interact with each other for testing
-- `test` stage - an ephemeral, primarily local, developer-only stack in which developers run local code against for testing
+ehmpathy recognizes three standard tiers in which applications run throughout their development cycle
+- `prod` — a deployed production stack the business depends on, which serves real customers
+- `prep` — a deployed pre-production stack where applications interact for cross-service tests
+- `test` — an ephemeral, primarily local, developer-only tier for local code
 
-this information is expected to be defined in the runtime environment through the following environmental variables
-- `STAGE` env var - explicitly defines the stage
-- `NODE_ENV` env var - implicitly defines the stage if `STAGE` was not explicitly defined
+`access` is the one canonical axis (`test | prep | prod`). the runtime reads it via
+`getEnvironment.static().access` (sdk-environment), which derives it from the `ACCESS` env var, then
+the aws account, then `NODE_ENV`.
 
 # vocab
 
 definitions
-- `stage`
-  - > A stage is a stack that you deploy for a specific purpose.
-
 - `stack`
   - > A stack is your application plus everything that it requires to run. This can include (but is not limited to) networks, servers, storage folders, Docker containers, build pipelines, etc.
 
@@ -26,3 +24,38 @@ definitions
 
 ref
 - https://www.tinystacks.com/blog-post/what-are-stacks-stages-and-environments/
+
+# the access axis, and how a caller reaches a peer lambda
+
+one fact — which deployment a runtime reaches — is named by `access` (`test | prep | prod`).
+below prod the deployed resource names carry a legacy `dev` label, so an `access=prep` runtime must
+reach resources named `-dev-`. that mismatch (`access=prep` ⟺ deployed name `dev`) is a
+compiler-invisible fault: both are `string`, so a wrong reference is green at build and red only at
+runtime, against a deployed resource.
+
+`src/access/sdks/` holds the transitional bridge that lets a caller reach a peer lambda by the slug
+the peer actually publishes at, per callee — one procedure per file (`rule.require.single-responsibility`):
+
+- `sdkAwsLambdaEnvAccessAncient.ts` → `sdkAwsLambdaEnvAccessAncient()` — emits the legacy `dev` slug
+  below prod. for a peer still published under `-dev-` only. carries the shared `LambdaEnvSlug` type.
+- `sdkAwsLambdaEnvAccessContemp.ts` → `sdkAwsLambdaEnvAccessContemp()` — emits the access direct.
+  for a `-prep-` peer, or self.
+
+## the migration ledger
+
+the helper choice IS the ledger: `grep AccessAncient` across a repo lists every peer still on the
+ancient (`-dev-` only) slug. a per-peer migration is a one-line `Ancient → Contemp` flip. once the
+org's last `Ancient` import is gone, the ancient branch, the `-dev-` publish, and the divergent
+`dev` slug retire together — the helper is scaffold built to be torn down.
+
+`ancient`/`contemp` is `sdk-aws-lambda`'s own vocabulary (it names the payload-format axis there);
+the `EnvAccess` qualifier disambiguates this slug-axis sense from that homograph.
+
+## the helper is a shared primitive
+
+the helper is a pure, shared target-resolution primitive that a consumer wires when it migrates a
+peer, so a fresh consumer holds it with no call site yet. the caller-side wire-up and the helper's
+retirement both land at the north-star endpoint.
+
+the full transition design (dual-publish, the ledger, the deletion endpoint) is the north-star of
+the fix-lambdas wish — see `.behavior/v2026_08_31.fix-lambdas-3/1.vision.yield.md` in this repo.

package/dist/practices/environments/best-practice/src/access/sdks/sdkAwsLambdaEnvAccessAncient.ts

@@ -0,0 +1,32 @@
+import type { EnvironmentAccessTier } from 'sdk-environment';
+
+import { envStatic } from '@src/utils/environment';
+
+/**
+ * .what = the fleet slug a caller addresses a peer lambda by.
+ * .why  = it is an access (`test | prep | prod`) OR the legacy `dev` slug an
+ *         ancient peer still publishes under. a first-class `dev` member keeps the slug
+ *         compiler-tracked — never an `as`-cast that lies a `dev` value through a type
+ *         that forbids it (the exact silent fault this transition exists to kill).
+ */
+export type LambdaEnvSlug = EnvironmentAccessTier | 'dev';
+
+/**
+ * .what = address an **ancient** peer — one that publishes `-dev-` only.
+ * .why  = `askLambdaEndpoint` builds its target as `${service}-${access}-${function}`.
+ *         an ancient peer publishes under a legacy `dev` slug that disagrees with
+ *         **access** (`test | prep | prod`) below prod (`access=prep` ⟺ deployed name
+ *         `dev`). so a caller emits the legacy `dev` slug below prod, because that is the
+ *         only name the peer publishes. `prod` maps to `prod` on both.
+ * .note = the helper choice IS the migration ledger: `grep AccessAncient` lists every
+ *         peer still published under `-dev-` only. once zero remain, this ancient branch
+ *         — and the divergent `dev` slug — retire together, alongside its contemp
+ *         counterpart `sdkAwsLambdaEnvAccessContemp`. the return type is `LambdaEnvSlug`,
+ *         so the `dev` slug flows with a compiler-tracked type — no cast, no lie.
+ */
+export const sdkAwsLambdaEnvAccessAncient = (
+  input?: { access: EnvironmentAccessTier | null },
+): LambdaEnvSlug => {
+  const access = input?.access ?? envStatic.access;
+  return access === 'prod' ? 'prod' : 'dev';
+};

package/dist/practices/environments/best-practice/src/access/sdks/sdkAwsLambdaEnvAccessContemp.ts

@@ -0,0 +1,14 @@
+import type { EnvironmentAccessTier } from 'sdk-environment';
+
+import { envStatic } from '@src/utils/environment';
+
+/**
+ * .what = address a **contemp** peer, or **self** — one that publishes `-prep-`.
+ * .why  = emit the access direct; no bridge is needed once the callee is
+ *         published under the access slug. the contemp counterpart of
+ *         `sdkAwsLambdaEnvAccessAncient`: as peers migrate, a caller flips
+ *         `Ancient → Contemp` per peer, and `grep AccessAncient` at zero is the exit.
+ */
+export const sdkAwsLambdaEnvAccessContemp = (
+  input?: { access: EnvironmentAccessTier | null },
+): EnvironmentAccessTier => input?.access ?? envStatic.access;

package/dist/practices/environments/best-practice/src/utils/environment.ts

@@ -4,5 +4,6 @@ export { getEnvironment };
 
 export const envStatic = getEnvironment.static();
 
-export const stage = envStatic.access;
-export const serviceClientStage = stage === 'prod' ? 'prod' : 'prep';
+// the access (`test | prep | prod`), re-exported flat for convenience. one axis, never a
+// divergent deploy slug.
+export const access = envStatic.access;

package/dist/practices/errors/.declapract.integration.test.ts

@@ -0,0 +1,121 @@
+import { relative } from 'node:path';
+
+import { given, then, useBeforeAll, when } from 'test-fns';
+
+import { getAllPathsUnderDir } from '../../utils/getAllPathsUnderDir';
+
+/**
+ * .what = holds the `own-implementation` bad-practice to a catch-all `src` glob (matches at any
+ *         depth), so it catches a consumer's own `UnexpectedCodePathError.ts` no matter which
+ *         directory segment holds it (D48 / #571).
+ * .why  = a declapract declaration's FILENAME is its target glob. the declaration was pinned to the
+ *         literal `src/utils/errors/UnexpectedCodePathError.ts`, so a consumer that keeps its own
+ *         implementation one segment away — `src/domain/errors/…`, `src/errors/…` — was NEVER
+ *         matched, and the bad practice silently never fired. its two kin (`error-fns`,
+ *         `local-error-imports`) already glob every `.ts` at any depth; this holds
+ *         `own-implementation` to the same catch-all so the miss-by-one-segment case cannot recur.
+ * .note = this is an INTEGRATION test by the same rule the kin `domain` walk cites — it reads the
+ *         filesystem (`readdirSync` over the bad-practice tree), and
+ *         `rule.forbid.unit.remote-boundaries` puts any test that reads the filesystem in the
+ *         integration suite. it needs no credential and no network; the boundary alone classifies it.
+ */
+
+const BAD_PRACTICES_DIR = `${__dirname}/bad-practices`;
+const CATCH_ALL_PREFIX = 'src/**/';
+
+/**
+ * .what = every declaration path (`*.declapract.ts`, minus tests) under a bad-practice dir, walked
+ *         with node's own readdir
+ */
+const getAllDeclarationPathsUnderDir = (input: { dir: string }): string[] =>
+  getAllPathsUnderDir({ dir: input.dir, skip: null }).filter(
+    (path) =>
+      /\.declapract\.ts$/.test(path) && !/\.declapract\.test\.ts$/.test(path),
+  );
+
+/**
+ * .what = the CONSUMER target glob a declaration governs, relative to its bad-practice dir.
+ *         a `*.declapract.ts` declaration governs its filename minus that suffix — which, since the
+ *         filename may hold glob segments, IS the target glob declapract matches on.
+ */
+const asConsumerTargetGlob = (input: {
+  absPath: string;
+  badPracticeDir: string;
+}): string =>
+  relative(input.badPracticeDir, input.absPath).replace(/\.declapract\.ts$/, '');
+
+/**
+ * .what = the first path segment of a relative path (the head dir, before the first `/`).
+ * .why  = a pure transformer leaf, named so the composer below reads intent rather than an
+ *         inline positional `.split('/')[0]` a reader must simulate to know which segment lands.
+ */
+const asFirstPathSegment = (input: { relPath: string }): string =>
+  input.relPath.split('/')[0]!;
+
+/**
+ * .what = the bad-practice dir that governs a declaration = its first path segment under
+ *         BAD_PRACTICES_DIR. a declaration's consumer glob is computed relative to this, so the
+ *         `own-implementation/` (etc) segment is stripped before the `src/` check.
+ */
+const asBadPracticeDir = (input: { absPath: string }): string =>
+  `${BAD_PRACTICES_DIR}/${asFirstPathSegment({
+    relPath: relative(BAD_PRACTICES_DIR, input.absPath),
+  })}`;
+
+describe('errors practice — catch-all glob paths (D48 clamp)', () => {
+  given('[case1] the `own-implementation` bad-practice', () => {
+    const badPracticeDir = `${BAD_PRACTICES_DIR}/own-implementation`;
+    const scene = useBeforeAll(() => ({
+      targetGlobs: getAllDeclarationPathsUnderDir({ dir: badPracticeDir }).map(
+        (absPath) => asConsumerTargetGlob({ absPath, badPracticeDir }),
+      ),
+    }));
+
+    when('[t0] its declared consumer target globs are gathered', () => {
+      then('it governs UnexpectedCodePathError.ts under a catch-all src glob at any depth', () => {
+        // teeth: the pre-fix declaration at `src/utils/errors/UnexpectedCodePathError.ts.declapract.ts`
+        // governs the literal `src/utils/errors/UnexpectedCodePathError.ts` — no catch-all segment —
+        // so a revert to the pinned path reddens this assertion.
+        expect(scene.targetGlobs).toContain(
+          `${CATCH_ALL_PREFIX}UnexpectedCodePathError.ts`,
+        );
+      });
+
+      then('no declaration pins the file to a fixed intermediate segment', () => {
+        // every declaration under this bad-practice that governs a src-tree file must glob at any
+        // depth; a fixed intermediate dir (e.g. `src/utils/errors/…`) is the miss-by-one-segment
+        // defect D48 names.
+        const pinnedToFixedSegment = scene.targetGlobs.filter(
+          (glob) => glob.startsWith('src/') && !glob.startsWith(CATCH_ALL_PREFIX),
+        );
+        expect(pinnedToFixedSegment).toEqual([]);
+      });
+    });
+  });
+
+  given('[case2] every error bad-practice that governs a src-tree file', () => {
+    const scene = useBeforeAll(() => ({
+      // gather the src-tree target globs across ALL error bad-practices, so the catch-all
+      // convention is held for the whole practice, not just `own-implementation`. each
+      // declaration's bad-practice dir is its first path segment under BAD_PRACTICES_DIR, so the
+      // consumer glob is computed relative to the practice that governs it.
+      srcTargetGlobs: getAllDeclarationPathsUnderDir({ dir: BAD_PRACTICES_DIR })
+        .map((absPath) =>
+          asConsumerTargetGlob({
+            absPath,
+            badPracticeDir: asBadPracticeDir({ absPath }),
+          }),
+        )
+        .filter((glob) => glob.startsWith('src/')),
+    }));
+
+    when('[t0] their consumer target globs are gathered', () => {
+      then('every src-tree declaration globs at any depth', () => {
+        const notCatchAll = scene.srcTargetGlobs.filter(
+          (glob) => !glob.startsWith(CATCH_ALL_PREFIX),
+        );
+        expect(notCatchAll).toEqual([]);
+      });
+    });
+  });
+});

package/dist/practices/errors/bad-practices/own-implementation/src/<star><star>/UnexpectedCodePathError.ts.declapract.ts

@@ -0,0 +1,8 @@
+import { FileCheckType } from 'declapract';
+
+// the declaration path is a catch-all glob (`src/**/UnexpectedCodePathError.ts`), not the
+// literal `src/utils/errors/UnexpectedCodePathError.ts`. a consumer's own implementation one
+// directory segment away (e.g. `src/domain/errors/UnexpectedCodePathError.ts`) must still be
+// caught — a literal path silently passes the miss-by-one-segment case, so the own-implementation
+// bad practice would never fire for it.
+export const check = FileCheckType.EXISTS;

package/dist/practices/errors/best-practice/package.json

@@ -1,5 +1,5 @@
 {
   "dependencies": {
-    "helpful-errors": "@declapract{check.minVersion('1.7.3')}"
+    "helpful-errors": "@declapract{check.minVersion('1.7.5')}"
   }
 }