@cosmicdrift/kumiko-framework 0.389.0 → 0.390.0

package/src/scripts/codemod/pii-personal-migration.ts

@@ -1,816 +0,0 @@
-#!/usr/bin/env bun
-// Migrates create*Field(...) calls from the old flag-based PII API (pii,
-// userOwned, tenantOwned, subjectRef, allowPlaintext, lookupable,
-// searchable, sensitive) to the author-facing personal/find API.
-// Idempotent — re-running is a no-op on already migrated fields (skipped once
-// a `personal` property is present).
-//
-// Mapping table (exact):
-//   pii: true                           -> personal: "self"
-//   userOwned: { ownerField: "x" }      -> personal: { of: "x" }
-//   tenantOwned: true                   -> personal: "tenant"
-//   subjectRef: true                    -> personal: "ref"
-//   allowPlaintext: "R"                 -> personal: false, reason: "<R, normalized to snake_case>"
-//   lookupable: true (alone)            -> find: "exact"
-//   lookupable: true + searchable: true -> find: "fuzzy"
-//   searchable: true (alone)            -> find: "fuzzy"
-//   sensitive: true                     -> find: "secret"
-//   none of the above                   -> find: "none"
-// `find` only applies to text/longText fields, and only when the subject
-// is neither "ref" nor `personal: false` (see PersonalAnnotations in
-// packages/types/src/fields.ts). Never guesses: anything outside this
-// table is reported (file:line) instead of transformed.
-//
-// Usage: bun scripts/codemod/pii-personal-migration.ts <targetDir> [--dry-run | --report-stance]
-// --report-stance is read-only: it writes nothing and classifies fields
-// that carry no personal stance.
-
-import { readFileSync } from "node:fs";
-import { relative, resolve } from "node:path";
-import {
-  PII_DIRECT_NAME_HINTS,
-  PII_USER_OWNED_NAME_HINTS,
-  PII_USER_REFERENCE_NAME_HINTS,
-} from "@cosmicdrift/kumiko-framework/engine";
-import { Glob } from "bun";
-import {
-  type CallExpression,
-  Node,
-  type ObjectLiteralExpression,
-  Project,
-  type PropertyAssignment,
-  type SourceFile,
-  SyntaxKind,
-} from "ts-morph";
-
-const SUBJECT_FLAG_NAMES = [
-  "pii",
-  "userOwned",
-  "tenantOwned",
-  "subjectRef",
-  "allowPlaintext",
-] as const;
-type SubjectFlagName = (typeof SUBJECT_FLAG_NAMES)[number];
-
-// `create*Field` factories that accept `find` (text/longText) — see
-// packages/framework/src/engine/factories.ts.
-const TEXT_FIND_FACTORIES = new Set(["createTextField"]);
-const LONGTEXT_FIND_FACTORIES = new Set(["createLongTextField"]);
-// Accept `personal` but never `find` (PersonalAnnotationsNoFind).
-const NO_FIND_FACTORIES = new Set([
-  "createSelectField",
-  "createMultiSelectField",
-  "createNumberField",
-  "createBigIntField",
-  "createDecimalField",
-  "createEmbeddedField",
-  "createEmbeddedListField",
-  "createJsonbField",
-  "createDateField",
-  "createTimestampField",
-  "createTzField",
-  "createLocatedTimestampField",
-]);
-// No personal-annotation support at all — a subject flag here is a bug.
-const NO_PERSONAL_FACTORIES = new Set([
-  "createBooleanField",
-  "createMoneyField",
-  "createFileField",
-  "createImageField",
-  "createFilesField",
-  "createImagesField",
-  "createDerivedField",
-]);
-// Overrides live in argument position 1, not 0.
-const OVERRIDES_ARG_INDEX_1 = new Set(["createEmbeddedField", "createEmbeddedListField"]);
-
-const FIELD_FACTORY_RE = /^create\w*Field$/;
-
-type ReportEntry = { readonly file: string; readonly line: number; readonly note: string };
-const FIND_BUCKETS = [
-  "exact",
-  "fuzzy",
-  "none",
-  "secret",
-  "ref",
-  "personal-false",
-  "no-find",
-] as const;
-type FindBucket = (typeof FIND_BUCKETS)[number];
-
-const reports: ReportEntry[] = [];
-const newLookupableSites: ReportEntry[] = [];
-const counts: Record<FindBucket, number> = {
-  exact: 0,
-  fuzzy: 0,
-  none: 0,
-  secret: 0,
-  ref: 0,
-  "personal-false": 0,
-  "no-find": 0,
-};
-
-function report(node: Node, note: string): void {
-  reports.push({
-    file: node.getSourceFile().getFilePath(),
-    line: node.getStartLineNumber(),
-    note,
-  });
-}
-
-function isTrueLiteral(node: Node | undefined): boolean {
-  return !!node && node.getKind() === SyntaxKind.TrueKeyword;
-}
-
-function findProp(obj: ObjectLiteralExpression, name: string): PropertyAssignment | undefined {
-  const p = obj.getProperty(name);
-  return p && Node.isPropertyAssignment(p) ? p : undefined;
-}
-
-// Reason-string convention (infra/guards/guard-error-reasons.ts):
-// ^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*$ — lowercase snake_case, optional
-// dot-namespacing. Old allowPlaintext values are free-form kebab-case.
-function normalizeReasonSlug(raw: string): string {
-  const slug = raw
-    .trim()
-    .toLowerCase()
-    .replace(/[^a-z0-9.]+/g, "_")
-    .replace(/_+/g, "_")
-    .replace(/^[._]+|[._]+$/g, "");
-  return /^[0-9]/.test(slug) ? `_${slug}` : slug;
-}
-
-type FieldCall = { readonly name: string; readonly objArg: ObjectLiteralExpression };
-
-function collectFieldCalls(sourceFile: SourceFile): FieldCall[] {
-  const calls: FieldCall[] = [];
-  for (const call of sourceFile.getDescendantsOfKind(SyntaxKind.CallExpression)) {
-    const exprNode = call.getExpression();
-    if (!Node.isIdentifier(exprNode)) continue;
-    const name = exprNode.getText();
-    // `createTenantConfig`/`createUserConfig`/etc. never match — they
-    // don't end in "Field", so they're out of scope by construction.
-    if (!FIELD_FACTORY_RE.test(name)) continue;
-
-    const argIndex = OVERRIDES_ARG_INDEX_1.has(name) ? 1 : 0;
-    const objArg = call.getArguments()[argIndex];
-    if (objArg && Node.isObjectLiteralExpression(objArg)) {
-      calls.push({ name, objArg });
-    }
-  }
-  return calls;
-}
-
-function reportRawSubjectLiterals(
-  sourceFile: SourceFile,
-  handled: ReadonlySet<ObjectLiteralExpression>,
-): void {
-  for (const objLit of sourceFile.getDescendantsOfKind(SyntaxKind.ObjectLiteralExpression)) {
-    if (handled.has(objLit)) continue;
-    const found = [...SUBJECT_FLAG_NAMES, "piiEncrypted"].filter((n) => objLit.getProperty(n));
-    if (found.length > 0) {
-      report(
-        objLit,
-        `subject flag(s) [${found.join(", ")}] on an object literal that is not a create*Field(...) call`,
-      );
-    }
-  }
-}
-
-type SubjectProp = { readonly name: SubjectFlagName; readonly prop: PropertyAssignment };
-type PersonalInit = { readonly personal: string; readonly reason: string | undefined };
-type FindSupport = "text" | "longText" | "none";
-type FindabilityProps = {
-  readonly lookupable: PropertyAssignment | undefined;
-  readonly searchable: PropertyAssignment | undefined;
-  readonly sensitive: PropertyAssignment | undefined;
-};
-
-function singleSubjectFlag(obj: ObjectLiteralExpression): SubjectProp | undefined {
-  const subjectProps = SUBJECT_FLAG_NAMES.map((n) => ({ name: n, prop: findProp(obj, n) })).filter(
-    (x): x is { name: SubjectFlagName; prop: PropertyAssignment } => !!x.prop,
-  );
-  if (subjectProps.length === 0) {
-    // `searchable`/`sensitive` alone remain valid, unrelated FieldDef
-    // properties — left untouched. `lookupable` alone can never compile
-    // (always an excess property without a `personal` to attach `find`
-    // to). `anonymize` alone has no PersonalAnnotations arm to live on.
-    const lookupableProp = findProp(obj, "lookupable");
-    if (lookupableProp) {
-      report(
-        lookupableProp,
-        "lookupable without any subject annotation — no `personal` to attach `find` to",
-      );
-    }
-    const anonymizeProp = obj.getProperty("anonymize");
-    if (anonymizeProp) {
-      report(
-        anonymizeProp,
-        "anonymize without any subject annotation — no PersonalAnnotations arm accepts anonymize alone",
-      );
-    }
-    return undefined;
-  }
-  if (subjectProps.length > 1) {
-    const first = subjectProps[0];
-    if (first) {
-      report(
-        first.prop,
-        `multiple subject annotations on one field (${subjectProps.map((s) => s.name).join(", ")}) — needs a human decision on which subject is correct`,
-      );
-    }
-    return undefined;
-  }
-  return subjectProps[0];
-}
-
-function findSupportOf(factoryName: string, subject: SubjectProp): FindSupport | undefined {
-  if (NO_PERSONAL_FACTORIES.has(factoryName)) {
-    report(
-      subject.prop,
-      `${factoryName} has no personal-annotation support — subject flag "${subject.name}" cannot be expressed here`,
-    );
-    return undefined;
-  }
-  if (TEXT_FIND_FACTORIES.has(factoryName)) return "text";
-  if (LONGTEXT_FIND_FACTORIES.has(factoryName)) return "longText";
-  if (NO_FIND_FACTORIES.has(factoryName)) return "none";
-  report(
-    subject.prop,
-    `unrecognized field factory "${factoryName}" — cannot verify its PersonalAnnotations shape`,
-  );
-  return undefined;
-}
-
-function personalFromTrueFlag(
-  personal: string,
-): (subject: SubjectProp) => PersonalInit | undefined {
-  return (subject) => {
-    if (isTrueLiteral(subject.prop.getInitializer())) return { personal, reason: undefined };
-    report(subject.prop, `${subject.name} is set to a non-\`true\` value — cannot infer intent`);
-    return undefined;
-  };
-}
-
-function personalFromAllowPlaintext(subject: SubjectProp): PersonalInit | undefined {
-  const init = subject.prop.getInitializer();
-  if (!init) {
-    report(subject.prop, "allowPlaintext has no value");
-    return undefined;
-  }
-  const reason = Node.isStringLiteral(init)
-    ? `"${normalizeReasonSlug(init.getLiteralText())}"`
-    : init.getText();
-  return { personal: "false", reason };
-}
-
-function personalFromUserOwned(subject: SubjectProp): PersonalInit | undefined {
-  const init = subject.prop.getInitializer();
-  if (!init || !Node.isObjectLiteralExpression(init)) {
-    report(subject.prop, "userOwned value is not an object literal — cannot extract ownerField");
-    return undefined;
-  }
-  const ownerFieldInit = findProp(init, "ownerField")?.getInitializer();
-  if (!ownerFieldInit) {
-    report(subject.prop, 'userOwned is missing an "ownerField" property');
-    return undefined;
-  }
-  return { personal: `{ of: ${ownerFieldInit.getText()} }`, reason: undefined };
-}
-
-// One row per subject flag of the mapping table in the file header; a row
-// reports and returns undefined when the flag value cannot be mapped.
-const PERSONAL_INIT_BY_SUBJECT: Record<
-  SubjectFlagName,
-  (subject: SubjectProp) => PersonalInit | undefined
-> = {
-  pii: personalFromTrueFlag(`"self"`),
-  userOwned: personalFromUserOwned,
-  tenantOwned: personalFromTrueFlag(`"tenant"`),
-  subjectRef: personalFromTrueFlag(`"ref"`),
-  allowPlaintext: personalFromAllowPlaintext,
-};
-
-// These PersonalAnnotations arms carry no `find` field at all.
-function migrateFindlessSubject(
-  obj: ObjectLiteralExpression,
-  subject: SubjectProp,
-  personal: PersonalInit,
-  lookupableProp: PropertyAssignment | undefined,
-): void {
-  const isRef = subject.name === "subjectRef";
-  if (lookupableProp) {
-    report(
-      lookupableProp,
-      `lookupable combined with personal:${isRef ? '"ref"' : "false"} — findability doesn't apply to this subject, table has no mapping`,
-    );
-    // skip: reported above — lookupable doesn't apply to this subject, no mapping to migrate
-    return;
-  }
-  applyTransform(obj, [subject.prop], {
-    personal: personal.personal,
-    reason: personal.reason,
-    find: undefined,
-  });
-  counts[isRef ? "ref" : "personal-false"]++;
-}
-
-function migrateNoFindField(
-  obj: ObjectLiteralExpression,
-  factoryName: string,
-  subject: SubjectProp,
-  personal: PersonalInit,
-  findability: FindabilityProps,
-): void {
-  const stray = findability.lookupable ?? findability.searchable ?? findability.sensitive;
-  if (stray) {
-    report(
-      stray,
-      `${factoryName} has no \`find\` in its PersonalAnnotations — findability flag present on a non-text field`,
-    );
-    // skip: reported above — findability flag on a non-text field, no valid find to attach
-    return;
-  }
-  applyTransform(obj, [subject.prop], {
-    personal: personal.personal,
-    reason: undefined,
-    find: undefined,
-  });
-  counts["no-find"]++;
-}
-
-// lookupable + searchable and searchable alone both map to "fuzzy".
-function findValueOf(findability: FindabilityProps): "exact" | "fuzzy" | "none" | "secret" {
-  if (findability.sensitive) return "secret";
-  if (findability.searchable) return "fuzzy";
-  if (findability.lookupable) return "exact";
-  return "none";
-}
-
-function migrateTextFindField(
-  obj: ObjectLiteralExpression,
-  subject: SubjectProp,
-  personal: PersonalInit,
-  findability: FindabilityProps,
-  support: Exclude<FindSupport, "none">,
-): void {
-  const { lookupable, searchable, sensitive } = findability;
-  if (sensitive && (lookupable || searchable)) {
-    report(
-      sensitive,
-      'sensitive combined with lookupable/searchable — two find values ("secret" vs "exact"/"fuzzy"), needs a human decision',
-    );
-    // skip: reported above — sensitive plus lookupable/searchable is an ambiguous find value
-    return;
-  }
-
-  const find = findValueOf(findability);
-  if (support === "longText" && (find === "exact" || find === "fuzzy")) {
-    const findSite = lookupable ?? searchable;
-    if (findSite) {
-      report(
-        findSite,
-        'lookupable/searchable on createLongTextField — only "none"/"secret" are valid find values on longText',
-      );
-    }
-    // skip: reported above — exact/fuzzy find isn't valid on createLongTextField
-    return;
-  }
-
-  // searchable-alone -> "fuzzy" makes expandPersonalAnnotations add
-  // `lookupable: true`, which the field didn't carry before — that's a
-  // new `_bidx` column (DDL migration), tracked separately for the report.
-  if (searchable && !lookupable) {
-    newLookupableSites.push({
-      file: obj.getSourceFile().getFilePath(),
-      line: subject.prop.getStartLineNumber(),
-      // Guard keys on property name `reason`; this is console copy, not an error code.
-      note: "needs a `_bidx` column migration",
-    });
-  }
-
-  const removedProps = [subject.prop, lookupable, searchable, sensitive].filter(
-    (p): p is PropertyAssignment => !!p,
-  );
-  applyTransform(obj, removedProps, { personal: personal.personal, reason: undefined, find });
-  counts[find]++;
-}
-
-function processObjectLiteral(obj: ObjectLiteralExpression, factoryName: string): void {
-  // skip: field already carries `personal` — already migrated, idempotent no-op
-  if (obj.getProperty("personal")) return;
-
-  const piiEncryptedProp = obj.getProperty("piiEncrypted");
-  if (piiEncryptedProp) {
-    report(
-      piiEncryptedProp,
-      "piiEncrypted: true on an entity field (removed from the type system) — needs a human decision, not a mechanical mapping",
-    );
-    // skip: reported above — piiEncrypted needs a human decision, not a mechanical mapping
-    return;
-  }
-
-  const subject = singleSubjectFlag(obj);
-  // skip: no subject flag, or several, reported by singleSubjectFlag where needed
-  if (!subject) return;
-  const support = findSupportOf(factoryName, subject);
-  // skip: factory without a verifiable PersonalAnnotations shape, reported by findSupportOf
-  if (!support) return;
-  const personal = PERSONAL_INIT_BY_SUBJECT[subject.name](subject);
-  // skip: flag value cannot be mapped, reported by its PERSONAL_INIT_BY_SUBJECT row
-  if (!personal) return;
-
-  const findability: FindabilityProps = {
-    lookupable: findProp(obj, "lookupable"),
-    searchable: findProp(obj, "searchable"),
-    sensitive: findProp(obj, "sensitive"),
-  };
-  if (subject.name === "subjectRef" || subject.name === "allowPlaintext") {
-    migrateFindlessSubject(obj, subject, personal, findability.lookupable);
-  } else if (support === "none") {
-    migrateNoFindField(obj, factoryName, subject, personal, findability);
-  } else {
-    migrateTextFindField(obj, subject, personal, findability, support);
-  }
-}
-
-function applyTransform(
-  obj: ObjectLiteralExpression,
-  removedProps: readonly PropertyAssignment[],
-  next: { personal: string; reason: string | undefined; find: string | undefined },
-): void {
-  const properties = obj.getProperties();
-  // Call sites always pass at least subject.prop; without an anchor there is nowhere to insert.
-  const anchor = removedProps[0];
-  if (!anchor) {
-    // skip: no removed prop to anchor inserts on — nothing to transform
-    return;
-  }
-  const anchorIndex = properties.indexOf(anchor);
-  const removedSet = new Set<PropertyAssignment>(removedProps);
-  let insertIndex = 0;
-  for (let i = 0; i < anchorIndex; i++) {
-    const property = properties[i];
-    if (!(property && Node.isPropertyAssignment(property) && removedSet.has(property)))
-      insertIndex++;
-  }
-
-  for (const p of removedProps) p.remove();
-
-  const newProps: { name: string; initializer: string }[] = [
-    { name: "personal", initializer: next.personal },
-  ];
-  if (next.find) newProps.push({ name: "find", initializer: `"${next.find}"` });
-  if (next.reason !== undefined) newProps.push({ name: "reason", initializer: next.reason });
-
-  obj.insertPropertyAssignments(insertIndex, newProps);
-}
-
-function findSourceFiles(rootDir: string, extraExcludes: readonly string[] = []): string[] {
-  const glob = new Glob("**/*.{ts,tsx}");
-  const EXCLUDE = ["/node_modules/", "/dist/", "/build/", ...extraExcludes];
-  const files: string[] = [];
-  for (const file of glob.scanSync({ cwd: rootDir, dot: false })) {
-    if (file.endsWith(".d.ts")) continue;
-    const abs = resolve(rootDir, file);
-    if (EXCLUDE.some((p) => abs.includes(p))) continue;
-    files.push(abs);
-  }
-  return files.sort();
-}
-
-export type StanceClass = "direct" | "user-owned" | "user-reference" | "near-miss" | "unclassified";
-
-export type HintCategory = "direct" | "user-owned" | "user-reference";
-
-export type StanceSite = {
-  readonly line: number;
-  readonly field: string;
-  readonly entity: string | null;
-  readonly callee: string;
-  readonly stance: StanceClass;
-  readonly hint: string | undefined;
-  readonly nearMissOf: HintCategory | undefined;
-};
-
-type CategorizedHint = readonly [hint: string, category: HintCategory];
-
-const ALL_PII_NAME_HINTS: readonly CategorizedHint[] = [
-  ...[...PII_DIRECT_NAME_HINTS].map((hint): CategorizedHint => [hint, "direct"]),
-  ...[...PII_USER_OWNED_NAME_HINTS].map((hint): CategorizedHint => [hint, "user-owned"]),
-  ...[...PII_USER_REFERENCE_NAME_HINTS].map((hint): CategorizedHint => [hint, "user-reference"]),
-];
-
-type FieldClassification = {
-  readonly stance: StanceClass;
-  readonly hint: string | undefined;
-  readonly nearMissOf: HintCategory | undefined;
-};
-
-const REPORT_STANCE_CALLEES = new Set(["createTextField", "createLongTextField"]);
-
-// Mirrors guard-text-field-stance.ts's hasPersonalStance exactly.
-function reportStanceHasPersonalStance(obj: ObjectLiteralExpression): boolean {
-  const prop = obj.getProperty("personal");
-  if (!prop || !Node.isPropertyAssignment(prop)) return false;
-  const init = prop.getInitializer();
-  return (
-    init !== undefined &&
-    init.getKind() !== SyntaxKind.UndefinedKeyword &&
-    !(Node.isIdentifier(init) && init.getText() === "undefined") &&
-    init.getKind() !== SyntaxKind.NullKeyword
-  );
-}
-
-function reportStanceEnclosingFieldName(call: CallExpression): string | undefined {
-  let node = call.getParent();
-  while (node) {
-    if (Node.isPropertyAssignment(node)) {
-      // getName() keeps the quotes of a string-literal key; computed keys have no static name.
-      const nameNode = node.getNameNode();
-      if (Node.isStringLiteral(nameNode) || Node.isNoSubstitutionTemplateLiteral(nameNode)) {
-        return nameNode.getLiteralText();
-      }
-      return Node.isIdentifier(nameNode) ? nameNode.getText() : undefined;
-    }
-    node = node.getParent();
-  }
-  return undefined;
-}
-
-function reportStanceResolveEntity(call: CallExpression): string | null {
-  let node: Node | undefined = call.getParent();
-  let entityCall: CallExpression | undefined;
-  while (node) {
-    if (Node.isCallExpression(node)) {
-      const expr = node.getExpression();
-      if (Node.isIdentifier(expr) && expr.getText() === "createEntity") {
-        entityCall = node;
-        break;
-      }
-    }
-    node = node.getParent();
-  }
-  if (!entityCall) return null;
-
-  const firstArg = entityCall.getArguments()[0];
-  if (firstArg && Node.isObjectLiteralExpression(firstArg)) {
-    const tableProp = firstArg.getProperty("table");
-    if (tableProp && Node.isPropertyAssignment(tableProp)) {
-      const init = tableProp.getInitializer();
-      if (init && Node.isStringLiteral(init)) return init.getLiteralText();
-    }
-  }
-  const varDecl = entityCall.getParentIfKind(SyntaxKind.VariableDeclaration);
-  return varDecl ? varDecl.getName() : null;
-}
-
-function isSegmentStart(fieldOriginal: string, index: number): boolean {
-  return (
-    index === 0 || /[A-Z]/.test(fieldOriginal[index] ?? "") || fieldOriginal[index - 1] === "_"
-  );
-}
-
-// A hint only counts when it starts and ends on a segment boundary (index 0 /
-// end of field, an uppercase letter in the original, or `_`) — otherwise a
-// coincidental substring like "text" in "contextId" or "type" in "contentType"
-// would false-positive.
-function hintOccursAtBoundary(fieldLower: string, fieldOriginal: string, hint: string): boolean {
-  let searchFrom = 0;
-  for (;;) {
-    const index = fieldLower.indexOf(hint, searchFrom);
-    if (index === -1) return false;
-    const end = index + hint.length;
-    if (
-      isSegmentStart(fieldOriginal, index) &&
-      (end === fieldOriginal.length || isSegmentStart(fieldOriginal, end))
-    ) {
-      return true;
-    }
-    searchFrom = index + 1;
-  }
-}
-
-function findLongestBoundaryHint(
-  fieldLower: string,
-  fieldOriginal: string,
-): CategorizedHint | undefined {
-  let best: CategorizedHint | undefined;
-  for (const entry of ALL_PII_NAME_HINTS) {
-    const [hint] = entry;
-    if (best && hint.length <= best[0].length) continue;
-    if (hintOccursAtBoundary(fieldLower, fieldOriginal, hint)) best = entry;
-  }
-  return best;
-}
-
-function segmentAlignedSuffixes(fieldOriginal: string): string[] {
-  const fieldLower = fieldOriginal.toLowerCase();
-  const starts: number[] = [];
-  for (let index = 0; index < fieldOriginal.length; index++) {
-    if (isSegmentStart(fieldOriginal, index)) starts.push(index);
-  }
-  // Hints are lowercase, so a hint's own segment boundary is unknowable. A
-  // single-segment tail ("Number", "Owner") is too generic to align with one;
-  // two or more segments ("UserId") are specific enough.
-  return starts.slice(0, -1).map((index) => fieldLower.slice(index));
-}
-
-// The hint sets only carry exact full names, so a suffix variant of one
-// (e.g. "...UserId" of "assigneeUserId") otherwise slips through undetected.
-// The suffix must be the tail of the hint: plain `includes` matched "number"
-// inside "phonenumber" for "orderNumber".
-function findShortestHintContainingSuffix(fieldOriginal: string): CategorizedHint | undefined {
-  let best: CategorizedHint | undefined;
-  for (const suffix of segmentAlignedSuffixes(fieldOriginal)) {
-    if (suffix.length < 5) continue;
-    for (const entry of ALL_PII_NAME_HINTS) {
-      const [hint] = entry;
-      if (hint === suffix || !hint.endsWith(suffix)) continue;
-      if (!best || hint.length < best[0].length) best = entry;
-    }
-  }
-  return best;
-}
-
-function classifyFieldStance(field: string): FieldClassification {
-  const fieldLower = field.replaceAll("_", "").toLowerCase();
-  if (PII_DIRECT_NAME_HINTS.has(fieldLower)) {
-    return { stance: "direct", hint: fieldLower, nearMissOf: undefined };
-  }
-  if (PII_USER_OWNED_NAME_HINTS.has(fieldLower)) {
-    return { stance: "user-owned", hint: fieldLower, nearMissOf: undefined };
-  }
-  if (PII_USER_REFERENCE_NAME_HINTS.has(fieldLower)) {
-    return { stance: "user-reference", hint: fieldLower, nearMissOf: undefined };
-  }
-  const nearMiss =
-    findLongestBoundaryHint(field.toLowerCase(), field) ?? findShortestHintContainingSuffix(field);
-  if (nearMiss) {
-    return { stance: "near-miss", hint: nearMiss[0], nearMissOf: nearMiss[1] };
-  }
-  return { stance: "unclassified", hint: undefined, nearMissOf: undefined };
-}
-
-function createReportStanceProject(): Project {
-  return new Project({ useInMemoryFileSystem: true, skipFileDependencyResolution: true });
-}
-
-export function reportStanceForSource(
-  source: string,
-  filePath: string,
-  project: Project = createReportStanceProject(),
-): StanceSite[] {
-  const sourceFile = project.createSourceFile(filePath, source, { overwrite: true });
-  try {
-    return collectStanceSites(sourceFile);
-  } finally {
-    // A shared project would otherwise keep every scanned file's AST alive.
-    project.removeSourceFile(sourceFile);
-  }
-}
-
-function collectStanceSites(sourceFile: SourceFile): StanceSite[] {
-  const sites: StanceSite[] = [];
-  for (const call of sourceFile.getDescendantsOfKind(SyntaxKind.CallExpression)) {
-    const exprNode = call.getExpression();
-    if (!Node.isIdentifier(exprNode)) continue;
-    const callee = exprNode.getText();
-    if (!REPORT_STANCE_CALLEES.has(callee)) continue;
-
-    const args = call.getArguments();
-    if (args.length > 0) {
-      const options = args[0];
-      if (!options || !Node.isObjectLiteralExpression(options)) continue;
-      if (options.getProperties().some((p) => p.isKind(SyntaxKind.SpreadAssignment))) continue;
-      if (reportStanceHasPersonalStance(options)) continue;
-    }
-
-    const enclosingField = reportStanceEnclosingFieldName(call);
-    // A call with no enclosing field (e.g. a bare createTextField() at top
-    // level) has no real name to classify — `createTextField(...)` would
-    // otherwise false-positive as a near-miss on its own "Text".
-    const { stance, hint, nearMissOf }: FieldClassification = enclosingField
-      ? classifyFieldStance(enclosingField)
-      : { stance: "unclassified", hint: undefined, nearMissOf: undefined };
-
-    sites.push({
-      line: call.getStartLineNumber(),
-      field: enclosingField ?? `${callee}(...)`,
-      entity: reportStanceResolveEntity(call),
-      callee,
-      stance,
-      hint,
-      nearMissOf,
-    });
-  }
-  return sites;
-}
-
-function formatHintSuffix(site: StanceSite): string {
-  if (!site.hint) return "";
-  return site.nearMissOf
-    ? ` (hint: ${site.hint}, near ${site.nearMissOf})`
-    : ` (hint: ${site.hint})`;
-}
-
-function reportStance(rootDir: string): void {
-  console.log(
-    `Scanning every .ts/.tsx under ${rootDir} except node_modules/dist/build/*.d.ts — guard-text-field-stance scans packages/*/src/** only, so counts can differ outside that scope.`,
-  );
-
-  const totals: Record<StanceClass, number> = {
-    direct: 0,
-    "user-owned": 0,
-    "user-reference": 0,
-    "near-miss": 0,
-    unclassified: 0,
-  };
-  let total = 0;
-
-  const project = createReportStanceProject();
-  for (const file of findSourceFiles(rootDir)) {
-    const sites = reportStanceForSource(readFileSync(file, "utf8"), file, project);
-    if (sites.length === 0) continue;
-
-    console.log(`\n${relative(rootDir, file)}`);
-    for (const site of sites) {
-      totals[site.stance]++;
-      total++;
-      const entity = site.entity ?? "<unresolved>";
-      const hintSuffix = formatHintSuffix(site);
-      console.log(
-        `  ${site.line}  ${site.field}  entity=${entity}  ${site.callee}  ${site.stance}${hintSuffix}`,
-      );
-    }
-  }
-
-  console.log("\nBy stance:");
-  for (const [stance, count] of Object.entries(totals)) {
-    if (count > 0) console.log(`  ${stance}: ${count}`);
-  }
-  console.log(`Total: ${total}`);
-
-  if (totals["near-miss"] > 0) {
-    console.log(
-      "\nHint sets in entity-handler.ts are exact name matches — near-miss field names slip past the boot heuristic.",
-    );
-  }
-}
-
-async function main(): Promise<void> {
-  const positional = process.argv.slice(2).filter((a) => !a.startsWith("--"));
-  const rootDir = resolve(positional[0] ?? process.cwd());
-
-  if (process.argv.includes("--report-stance")) {
-    reportStance(rootDir);
-    // skip: report mode never rewrites, so the transform path below must not run
-    return;
-  }
-
-  const dryRun = process.argv.includes("--dry-run");
-  // engine/factories.ts constructs raw ResolvedPiiFlags literals as the
-  // *implementation* of expandPersonalAnnotations (personal -> flags) —
-  // not an authored override, so it's not a migration target.
-  const files = findSourceFiles(rootDir, ["/engine/factories.ts"]);
-  const project = new Project({
-    skipAddingFilesFromTsConfig: true,
-    skipFileDependencyResolution: true,
-  });
-
-  let touchedFiles = 0;
-  for (const file of files) {
-    const sourceFile = project.addSourceFileAtPath(file);
-    const calls = collectFieldCalls(sourceFile);
-    const handled = new Set(calls.map((c) => c.objArg));
-    reportRawSubjectLiterals(sourceFile, handled);
-
-    const countsBefore = { ...counts };
-    for (const { name, objArg } of calls) processObjectLiteral(objArg, name);
-    const changed = FIND_BUCKETS.some((k) => counts[k] !== countsBefore[k]);
-
-    if (changed) {
-      touchedFiles++;
-      if (!dryRun) sourceFile.saveSync();
-    }
-  }
-
-  console.log(`\nScanned ${files.length} files under ${rootDir}${dryRun ? " (dry-run)" : ""}.`);
-  console.log(`Touched ${touchedFiles} files.\n`);
-  console.log("Transformed, by find/personal bucket:");
-  for (const [bucket, n] of Object.entries(counts)) {
-    if (n > 0) console.log(`  ${bucket}: ${n}`);
-  }
-  console.log(`\nNewly gains lookupable (needs a _bidx migration): ${newLookupableSites.length}`);
-  for (const r of newLookupableSites) {
-    console.log(`  ${relative(rootDir, r.file)}:${r.line} — ${r.note}`);
-  }
-  console.log(`\nReported (not transformed): ${reports.length}`);
-  for (const r of reports) {
-    console.log(`  ${relative(rootDir, r.file)}:${r.line} — ${r.note}`);
-  }
-}
-
-if (import.meta.main) {
-  await main();
-}