@cosmicdrift/kumiko-framework 0.335.0 → 0.336.1

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

@@ -21,7 +21,9 @@
 // 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]
+// 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";
@@ -423,14 +425,12 @@ function applyTransform(
   obj.insertPropertyAssignments(insertIndex, newProps);
 }
 
-function findTargetFiles(rootDir: string): string[] {
+function findSourceFiles(rootDir: string, extraExcludes: readonly string[] = []): string[] {
   const glob = new Glob("**/*.{ts,tsx}");
-  // 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 EXCLUDE = ["/node_modules/", "/dist/", "/build/", "/engine/factories.ts"];
+  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);
@@ -440,6 +440,8 @@ function findTargetFiles(rootDir: string): string[] {
 
 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;
@@ -447,14 +449,23 @@ export type StanceSite = {
   readonly callee: string;
   readonly stance: StanceClass;
   readonly hint: string | undefined;
+  readonly nearMissOf: HintCategory | undefined;
 };
 
-const ALL_PII_NAME_HINTS: readonly string[] = [
-  ...PII_DIRECT_NAME_HINTS,
-  ...PII_USER_OWNED_NAME_HINTS,
-  ...PII_USER_REFERENCE_NAME_HINTS,
+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.
@@ -539,11 +550,15 @@ function hintOccursAtBoundary(fieldLower: string, fieldOriginal: string, hint: s
   }
 }
 
-function findLongestBoundaryHint(fieldLower: string, fieldOriginal: string): string | undefined {
-  let best: string | undefined;
-  for (const hint of ALL_PII_NAME_HINTS) {
-    if (best && hint.length <= best.length) continue;
-    if (hintOccursAtBoundary(fieldLower, fieldOriginal, hint)) best = hint;
+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;
 }
@@ -564,29 +579,36 @@ function segmentAlignedSuffixes(fieldOriginal: string): string[] {
 // (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): string | undefined {
-  let best: string | undefined;
+function findShortestHintContainingSuffix(fieldOriginal: string): CategorizedHint | undefined {
+  let best: CategorizedHint | undefined;
   for (const suffix of segmentAlignedSuffixes(fieldOriginal)) {
     if (suffix.length < 5) continue;
-    for (const hint of ALL_PII_NAME_HINTS) {
+    for (const entry of ALL_PII_NAME_HINTS) {
+      const [hint] = entry;
       if (hint === suffix || !hint.endsWith(suffix)) continue;
-      if (!best || hint.length < best.length) best = hint;
+      if (!best || hint.length < best[0].length) best = entry;
     }
   }
   return best;
 }
 
-function classifyFieldStance(field: string): { stance: StanceClass; hint: string | undefined } {
+function classifyFieldStance(field: string): FieldClassification {
   const fieldLower = field.replaceAll("_", "").toLowerCase();
-  if (PII_DIRECT_NAME_HINTS.has(fieldLower)) return { stance: "direct", hint: fieldLower };
-  if (PII_USER_OWNED_NAME_HINTS.has(fieldLower)) return { stance: "user-owned", hint: fieldLower };
-  if (PII_USER_REFERENCE_NAME_HINTS.has(fieldLower))
-    return { stance: "user-reference", hint: fieldLower };
-  const containmentHint = findLongestBoundaryHint(field.toLowerCase(), field);
-  if (containmentHint) return { stance: "near-miss", hint: containmentHint };
-  const suffixHint = findShortestHintContainingSuffix(field);
-  if (suffixHint) return { stance: "near-miss", hint: suffixHint };
-  return { stance: "unclassified", hint: undefined };
+  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 {
@@ -627,9 +649,9 @@ function collectStanceSites(sourceFile: SourceFile): StanceSite[] {
     // 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 } = enclosingField
+    const { stance, hint, nearMissOf }: FieldClassification = enclosingField
       ? classifyFieldStance(enclosingField)
-      : { stance: "unclassified" as const, hint: undefined };
+      : { stance: "unclassified", hint: undefined, nearMissOf: undefined };
 
     sites.push({
       line: call.getStartLineNumber(),
@@ -638,22 +660,17 @@ function collectStanceSites(sourceFile: SourceFile): StanceSite[] {
       callee,
       stance,
       hint,
+      nearMissOf,
     });
   }
   return sites;
 }
 
-function findReportStanceFiles(rootDir: string): string[] {
-  const glob = new Glob("**/*.{ts,tsx}");
-  const EXCLUDE = ["/node_modules/", "/dist/", "/build/"];
-  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();
+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 {
@@ -671,7 +688,7 @@ function reportStance(rootDir: string): void {
   let total = 0;
 
   const project = createReportStanceProject();
-  for (const file of findReportStanceFiles(rootDir)) {
+  for (const file of findSourceFiles(rootDir)) {
     const sites = reportStanceForSource(readFileSync(file, "utf8"), file, project);
     if (sites.length === 0) continue;
 
@@ -680,7 +697,7 @@ function reportStance(rootDir: string): void {
       totals[site.stance]++;
       total++;
       const entity = site.entity ?? "<unresolved>";
-      const hintSuffix = site.hint ? ` (hint: ${site.hint})` : "";
+      const hintSuffix = formatHintSuffix(site);
       console.log(
         `  ${site.line}  ${site.field}  entity=${entity}  ${site.callee}  ${site.stance}${hintSuffix}`,
       );
@@ -711,7 +728,10 @@ async function main(): Promise<void> {
   }
 
   const dryRun = process.argv.includes("--dry-run");
-  const files = findTargetFiles(rootDir);
+  // 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,

package/src/scripts/codemod/unprocessable-error-details-reason.ts

@@ -105,9 +105,25 @@ function resolveDetailsProperty(optsLiteral: ObjectLiteralExpression): DetailsRe
 /** True if removing this shorthand-bound identifier would leave its declaration with no other use. */
 function wouldLeaveUnusedVariable(nameNode: Identifier): boolean {
   try {
-    const refs = nameNode.findReferencesAsNodes();
-    const others = refs.filter((r) => r !== nameNode);
-    return others.length === 0;
+    // The shorthand name resolves to the object-literal property symbol too, and
+    // a declaration counts as a reference, so look up the variable's own uses.
+    const shorthand = nameNode.getParent();
+    const variableSymbol = Node.isShorthandPropertyAssignment(shorthand)
+      ? shorthand.getValueSymbol()
+      : undefined;
+    const declarations = variableSymbol?.getDeclarations() ?? [];
+    const declarationNames = declarations.flatMap((declaration) =>
+      Node.isVariableDeclaration(declaration) || Node.isParameterDeclaration(declaration)
+        ? [declaration.getNameNode()]
+        : [],
+    );
+    // No resolvable declaration: can't verify, treat as unsafe.
+    if (declarationNames.length === 0) return true;
+    return declarationNames
+      .flatMap((declarationName) =>
+        Node.isIdentifier(declarationName) ? declarationName.findReferencesAsNodes() : [],
+      )
+      .every((usage) => usage === nameNode);
   } catch {
     // Can't verify — treat as unsafe rather than guess.
     return true;
@@ -122,12 +138,11 @@ type RemovalResult =
 /** Removes the `reason` property from a `details` object literal, in place. */
 function removeReasonProperty(detailsLiteral: ObjectLiteralExpression): RemovalResult {
   const properties = detailsLiteral.getProperties();
-  if (properties.some((p) => Node.isSpreadAssignment(p))) {
-    return {
-      kind: "skip",
-      note: "details object literal contains a spread — not statically decidable",
-    };
-  }
+  const hasSpread = properties.some((p) => Node.isSpreadAssignment(p));
+  const spreadSkip: RemovalResult = {
+    kind: "skip",
+    note: "details object literal has a spread next to an explicit reason — not statically decidable",
+  };
 
   for (const prop of properties) {
     if (Node.isPropertyAssignment(prop)) {
@@ -145,12 +160,14 @@ function removeReasonProperty(detailsLiteral: ObjectLiteralExpression): RemovalR
           ? nameNode.getLiteralText()
           : undefined;
       if (propName === "reason") {
+        if (hasSpread) return spreadSkip;
         prop.remove();
         return { kind: "removed" };
       }
       continue;
     }
     if (Node.isShorthandPropertyAssignment(prop) && prop.getName() === "reason") {
+      if (hasSpread) return spreadSkip;
       if (wouldLeaveUnusedVariable(prop.getNameNode())) {
         return {
           kind: "skip",
@@ -166,13 +183,20 @@ function removeReasonProperty(detailsLiteral: ObjectLiteralExpression): RemovalR
 
 type CallOutcome = "changed" | "skipped" | "not-a-match";
 
-function processNewExpression(args: readonly Node[], report: (note: string) => void): CallOutcome {
+// "manual": a concrete `reason` the codemod found but cannot remove safely.
+// "unverified": opts/details not statically analyzable — may well be fine, so
+// it is listed apart to keep the actionable list short.
+type SkipKind = "manual" | "unverified";
+type ReportSkip = (note: string, kind: SkipKind) => void;
+
+function processNewExpression(args: readonly Node[], report: ReportSkip): CallOutcome {
   const optsArg = args[1];
   if (!optsArg) return "not-a-match";
 
   if (!Node.isObjectLiteralExpression(optsArg)) {
     report(
       "second argument (opts) is not a statically-analyzable object literal — cannot verify details.reason",
+      "unverified",
     );
     return "skipped";
   }
@@ -180,14 +204,14 @@ function processNewExpression(args: readonly Node[], report: (note: string) => v
   const detailsRes = resolveDetailsProperty(optsArg);
   if (detailsRes.kind === "absent") return "not-a-match";
   if (detailsRes.kind === "unresolvable") {
-    report(detailsRes.note);
+    report(detailsRes.note, "unverified");
     return "skipped";
   }
 
   const removal = removeReasonProperty(detailsRes.literal);
   if (removal.kind === "absent") return "not-a-match";
   if (removal.kind === "skip") {
-    report(removal.note);
+    report(removal.note, "manual");
     return "skipped";
   }
   return "changed";
@@ -195,16 +219,14 @@ function processNewExpression(args: readonly Node[], report: (note: string) => v
 
 // `failUnprocessable(reason, details)` takes the details literal directly as
 // its second argument (no `{ details }` wrapper like the ctor's opts).
-function processFailUnprocessableCall(
-  args: readonly Node[],
-  report: (note: string) => void,
-): CallOutcome {
+function processFailUnprocessableCall(args: readonly Node[], report: ReportSkip): CallOutcome {
   const detailsArg = args[1];
   if (!detailsArg) return "not-a-match";
 
   if (!Node.isObjectLiteralExpression(detailsArg)) {
     report(
       "second argument (details) is not a statically-analyzable object literal — cannot verify details.reason",
+      "unverified",
     );
     return "skipped";
   }
@@ -212,18 +234,23 @@ function processFailUnprocessableCall(
   const removal = removeReasonProperty(detailsArg);
   if (removal.kind === "absent") return "not-a-match";
   if (removal.kind === "skip") {
-    report(removal.note);
+    report(removal.note, "manual");
     return "skipped";
   }
   return "changed";
 }
 
-type SkipEntry = { readonly file: string; readonly line: number; readonly note: string };
+type SkipEntry = {
+  readonly file: string;
+  readonly line: number;
+  readonly note: string;
+  readonly kind: SkipKind;
+};
 
 type MigratableCall = {
   readonly exportName: "UnprocessableError" | "failUnprocessable";
   readonly localKind: "class" | "function";
-  readonly process: (args: readonly Node[], report: (note: string) => void) => CallOutcome;
+  readonly process: (args: readonly Node[], report: ReportSkip) => CallOutcome;
 };
 
 const UNPROCESSABLE_ERROR_CTOR: MigratableCall = {
@@ -256,7 +283,7 @@ function migrateCallSite(
     const note = binding
       ? `${target.exportName} is imported from "${binding.moduleSpecifier}", not a @cosmicdrift/kumiko-* package`
       : `${target.exportName} has no @cosmicdrift/kumiko-* import in this file (likely a locally defined ${target.localKind})`;
-    skips.push({ file, line, note });
+    skips.push({ file, line, note, kind: "manual" });
     return false;
   }
   if (!KUMIKO_MODULE_RE.test(binding.moduleSpecifier)) {
@@ -264,11 +291,14 @@ function migrateCallSite(
       file,
       line,
       note: `${target.exportName} is imported from "${binding.moduleSpecifier}", not a @cosmicdrift/kumiko-* package`,
+      kind: "manual",
     });
     return false;
   }
 
-  const outcome = target.process(site.getArguments(), (note) => skips.push({ file, line, note }));
+  const outcome = target.process(site.getArguments(), (note, kind) =>
+    skips.push({ file, line, note, kind }),
+  );
   return outcome === "changed";
 }
 
@@ -320,9 +350,16 @@ async function main(): Promise<void> {
   console.log(
     `Touched ${touchedFiles} files, removed ${removedTotal} redundant "reason" propert(y/ies).`,
   );
-  console.log(`Skipped ${skips.length} site(s):`);
-  for (const s of skips) {
-    console.log(`  ${relative(rootDir, s.file)}:${s.line} — ${s.note}`);
+  for (const kind of ["manual", "unverified"] as const) {
+    const ofKind = skips.filter((s) => s.kind === kind);
+    console.log(
+      kind === "manual"
+        ? `Skipped ${ofKind.length} site(s) needing manual work:`
+        : `Unverified ${ofKind.length} site(s) (opts/details not statically analyzable, may be fine):`,
+    );
+    for (const s of ofKind) {
+      console.log(`  ${relative(rootDir, s.file)}:${s.line} — ${s.note}`);
+    }
   }
   console.log();
 }