@oneuptime/common 14.0.13 → 14.0.14

package/Tests/Helpers/FormStepsScan.ts

@@ -2,17 +2,22 @@ import fs from "fs";
 import path from "path";
 import ts from "typescript";
 import { RULE_ENABLED_COLUMN } from "../../UI/Components/RuleRun/RuleEnabledField";
+import { LocaleLookup, loadLocaleFor } from "../DialogActionRules";
 
 /*
  * The detector behind the "long forms walk steps" guard
- * (Tests/UI/Components/Forms/LongFormStepsGuard.test.ts) and the "no step
+ * (Tests/UI/Components/Forms/LongFormStepsGuard.test.ts), its other side -
+ * "short forms fit on one page" (findShortFormsWithSteps) - and the "no step
  * packs too many options" guard (OverloadedFormStepsGuard.test.ts, see
  * findOverloadedSteps at the end).
  *
  * The rule, in the maintainer's words: "have formsteps ... for any long forms
  * in the project (anything > 3 fields)". A form of more than three fields the
  * user can see is split into steps (FormStep, a field's stepId), or carries
- * an entry in the guard's allowlist that says why not.
+ * an entry in the guard's allowlist that says why not. And the other way
+ * round: a form of three rows or fewer is one page, with no stepper, unless
+ * its allowlist entry says why it walks steps - a wizard step has to earn its
+ * place, and three rows fit on one screen.
  *
  * What it reads. Every JSX use of the form hosts - ModelTable (and the
  * RuleTable / LabelRuleTable wrappers around it), CardModelDetail,
@@ -60,11 +65,11 @@ import { RULE_ENABLED_COLUMN } from "../../UI/Components/RuleRun/RuleEnabledFiel
  *     on a ModelTable, so is a step whose every field the Edit form leaves
  *     out.
  *
- * And, for the "finish from any step" guard (FinishFromAnyStepGuard.test.ts),
- * what a custom element draws: the components its getCustomElement renders
- * (following a render helper in the same file), where each is declared, and
- * whether it fills in a value of its own when it is drawn - an effect in it
- * that calls onChange (see CustomElementComponentFacts).
+ * And what a custom element draws: the components its getCustomElement
+ * renders (following a render helper in the same file), where each is
+ * declared, and whether it fills in a value of its own when it is drawn - an
+ * effect in it that calls onChange (see CustomElementComponentFacts). The
+ * Admin Dashboard's team picker is found that way (ProjectTeamFormsGuard).
  */
 
 export const LONG_FORM_FIELD_LIMIT: number = 3;
@@ -219,8 +224,6 @@ export interface FormFieldFacts {
    * helper returns another's field. Undefined for a field written out.
    */
   helper?: string | undefined;
-  // customElementCanBeSkipped written true (Forms/Utils/FinishFromAnyStep).
-  customElementCanBeSkipped: boolean;
   // What its getCustomElement draws; empty when it has none.
   customElementComponents: Array<CustomElementComponentFacts>;
   file: string;
@@ -230,7 +233,20 @@ export interface FormFieldFacts {
 export interface FormStepFacts {
   // The step's id when written as a string.
   id: string | null;
+  // The title written as a string, else its source text (`t("...")`).
   title: string;
+  /*
+   * Every text the title can be on screen, in English (readTitleTexts): a
+   * string, each branch of a condition, a constant it names, or a
+   * translation call's key looked up in the English locale of the front end
+   * the form is in - the Admin Dashboard's t("pages.x.stepAdvanced") and the
+   * status page's translate("subscribe.steps.details") read their nested
+   * keys there, while the Dashboard's translationKey("Advanced") and
+   * translateString("Advanced") key a text by its English. Null when the
+   * title cannot be read: computed some other way, or a key its locale does
+   * not have. Empty without a title.
+   */
+  titleTexts: Array<string> | null;
   isConditional: boolean;
 }
 
@@ -317,6 +333,13 @@ interface ParsedFile {
   // Every named declaration, first one wins: `const x = ...`, `function x`.
   declarations: Map<string, ts.Node>;
   imports: Map<string, { file: string; exported: string }>;
+  /*
+   * Names the file passes on from another (`export { X } from "./Copy"`),
+   * and the files it passes everything on from (`export * from "./Copy"`).
+   * Only a step's title is followed through them (readTitleTexts).
+   */
+  reexports: Map<string, { file: string; exported: string }>;
+  reexportedFiles: Array<string>;
   // Arguments of `<name>.push(...)` anywhere in the file.
   pushes: Map<string, Array<{ argument: ts.Expression; inLoop: boolean }>>;
   // Values of `<name> = ...` anywhere in the file.
@@ -402,6 +425,34 @@ function writtenStringsOf(expression: ts.Node): Array<string> | null {
   return null;
 }
 
+/*
+ * The calls a front end translates a string with, by the name they are
+ * called by (`t(...)`, `data.translate(...)`, `translator.translateText(...)`).
+ * The Admin Dashboard's t() and the status page's translate() look a key up
+ * in their own locale; translationKey() marks an English text for the
+ * Dashboard's extractor and translateString / translateText / translateValue
+ * / translateTerm / translateTemplate look it up, so their key - the first
+ * argument - is the English itself (a template's with its {{placeholders}}).
+ */
+export const TRANSLATION_CALLS: ReadonlySet<string> = new Set<string>([
+  "t",
+  "tx",
+  "translate",
+  "translationKey",
+  "translateString",
+  "translateText",
+  "translateValue",
+  "translateTerm",
+  "translateTemplate",
+]);
+
+/*
+ * A translation key that is a path into a nested locale ("pages.x.stepBasic",
+ * "subscribe.steps.details") rather than English text: dotted words, no
+ * spaces. One its locale does not have is drawn as the path itself.
+ */
+const NESTED_LOCALE_KEY: RegExp = /^[A-Za-z_$][\w$]*(\.[A-Za-z_$][\w$]*)+$/;
+
 function isInsideLoop(node: ts.Node): boolean {
   let current: ts.Node | undefined = node.parent;
 
@@ -434,6 +485,12 @@ export class FormStepsScanner {
     ParsedFile | null
   >();
 
+  // The English locale of each front end, read once (see readTitleTexts).
+  private readonly locales: Map<string, LocaleLookup> = new Map<
+    string,
+    LocaleLookup
+  >();
+
   public constructor(
     private readonly repositoryRoot: string,
     private readonly fileSystem: SourceFileSystem = REAL_FILE_SYSTEM,
@@ -503,6 +560,8 @@ export class FormStepsScanner {
       sourceFile,
       declarations: new Map<string, ts.Node>(),
       imports: new Map<string, { file: string; exported: string }>(),
+      reexports: new Map<string, { file: string; exported: string }>(),
+      reexportedFiles: [],
       pushes: new Map<
         string,
         Array<{ argument: ts.Expression; inLoop: boolean }>
@@ -595,6 +654,34 @@ export class FormStepsScanner {
         }
       }
 
+      if (
+        ts.isExportDeclaration(node) &&
+        node.moduleSpecifier &&
+        ts.isStringLiteral(node.moduleSpecifier)
+      ) {
+        const target: string | null = this.resolveModule(
+          filePath,
+          node.moduleSpecifier.text,
+        );
+
+        if (target && !node.exportClause) {
+          parsed.reexportedFiles.push(target);
+        }
+
+        if (
+          target &&
+          node.exportClause &&
+          ts.isNamedExports(node.exportClause)
+        ) {
+          for (const element of node.exportClause.elements) {
+            parsed.reexports.set(element.name.text, {
+              file: target,
+              exported: (element.propertyName || element.name).text,
+            });
+          }
+        }
+      }
+
       ts.forEachChild(node, collect);
     };
 
@@ -1900,7 +1987,6 @@ export class FormStepsScanner {
               .getText(collapsibleSection.getSourceFile())
               .replace(/\s+/g, "")
           : undefined,
-      customElementCanBeSkipped: isTrue("customElementCanBeSkipped"),
       customElementComponents: getCustomElement
         ? this.readDrawnComponents(getCustomElement)
         : [],
@@ -2031,6 +2117,7 @@ export class FormStepsScanner {
   ): FormStepFacts {
     let id: string | null = null;
     let title: string = "";
+    let titleTexts: Array<string> | null = [];
     let isConditional: boolean = false;
 
     for (const property of node.properties) {
@@ -2049,6 +2136,7 @@ export class FormStepsScanner {
         title = ts.isStringLiteralLike(value)
           ? value.text
           : value.getText(parsed.sourceFile);
+        titleTexts = this.readTitleTexts(parsed, value, 0);
       }
 
       if (name === "showIf") {
@@ -2056,8 +2144,288 @@ export class FormStepsScanner {
       }
     }
 
-    return { id, title, isConditional };
+    return { id, title, titleTexts, isConditional };
   }
+
+  /*
+   * The English texts a step's title can be on screen (FormStepFacts
+   * .titleTexts): a string; each branch of a condition; the value of a
+   * constant it names, in this file or imported (re-exports included), or
+   * of a property of a constant object of copy (`FormsCopy.stepDefaults`;
+   * every value, for `COPY.title[kind]`); or a translation call
+   * (TRANSLATION_CALLS) whose key is one of those, looked up in the English
+   * locale of the front end the form is in. A key that locale does not have
+   * is shown as itself - English text keys a Dashboard string - unless it is
+   * a nested path, which would be drawn as the path: that title cannot be
+   * read. Null for anything else.
+   */
+  private readTitleTexts(
+    parsed: ParsedFile,
+    expression: ts.Node,
+    depth: number,
+  ): Array<string> | null {
+    if (depth > MAX_DEPTH) {
+      return null;
+    }
+
+    const node: ts.Node = unwrap(expression);
+
+    if (ts.isStringLiteralLike(node)) {
+      return [node.text];
+    }
+
+    if (ts.isConditionalExpression(node)) {
+      const whenTrue: Array<string> | null = this.readTitleTexts(
+        parsed,
+        node.whenTrue,
+        depth + 1,
+      );
+      const whenFalse: Array<string> | null = this.readTitleTexts(
+        parsed,
+        node.whenFalse,
+        depth + 1,
+      );
+
+      return whenTrue && whenFalse ? [...whenTrue, ...whenFalse] : null;
+    }
+
+    if (ts.isIdentifier(node)) {
+      const declared: { parsed: ParsedFile; node: ts.Node } | null =
+        this.lookupValue(parsed, node.text, depth + 1);
+
+      return declared && ts.isExpression(declared.node)
+        ? this.readTitleTexts(declared.parsed, declared.node, depth + 1)
+        : null;
+    }
+
+    if (ts.isPropertyAccessExpression(node)) {
+      const owner: {
+        parsed: ParsedFile;
+        node: ts.ObjectLiteralExpression;
+      } | null = this.readObjectLiteral(parsed, node.expression, depth + 1);
+      const value: ts.Expression | null = owner
+        ? propertyValueOf(owner.node, node.name.text)
+        : null;
+
+      return owner && value
+        ? this.readTitleTexts(owner.parsed, value, depth + 1)
+        : null;
+    }
+
+    if (ts.isElementAccessExpression(node)) {
+      const owner: {
+        parsed: ParsedFile;
+        node: ts.ObjectLiteralExpression;
+      } | null = this.readObjectLiteral(parsed, node.expression, depth + 1);
+
+      if (!owner) {
+        return null;
+      }
+
+      const index: ts.Node = unwrap(node.argumentExpression);
+
+      if (ts.isStringLiteralLike(index)) {
+        const value: ts.Expression | null = propertyValueOf(
+          owner.node,
+          index.text,
+        );
+
+        return value
+          ? this.readTitleTexts(owner.parsed, value, depth + 1)
+          : null;
+      }
+
+      // Indexed at runtime: it can be any of the object's values.
+      const texts: Array<string> = [];
+
+      for (const property of owner.node.properties) {
+        if (!ts.isPropertyAssignment(property)) {
+          return null;
+        }
+
+        const read: Array<string> | null = this.readTitleTexts(
+          owner.parsed,
+          property.initializer,
+          depth + 1,
+        );
+
+        if (!read) {
+          return null;
+        }
+
+        texts.push(...read);
+      }
+
+      return texts.length > 0 ? texts : null;
+    }
+
+    if (ts.isCallExpression(node) && node.arguments[0]) {
+      const callee: ts.Expression = node.expression;
+      const calleeName: string | null = ts.isIdentifier(callee)
+        ? callee.text
+        : ts.isPropertyAccessExpression(callee)
+          ? callee.name.text
+          : null;
+
+      if (!calleeName || !TRANSLATION_CALLS.has(calleeName)) {
+        return null;
+      }
+
+      const keys: Array<string> | null = this.readTitleTexts(
+        parsed,
+        node.arguments[0],
+        depth + 1,
+      );
+
+      if (!keys) {
+        return null;
+      }
+
+      const locale: LocaleLookup = loadLocaleFor(
+        this.repositoryRoot,
+        toRepositoryPath(this.repositoryRoot, parsed.file),
+        this.locales,
+        (filePath: string): string | null => {
+          return this.fileSystem.readFile(filePath);
+        },
+      );
+      const texts: Array<string> = [];
+
+      for (const key of keys) {
+        const text: string | null = locale(key);
+
+        if (text === null && NESTED_LOCALE_KEY.test(key)) {
+          return null;
+        }
+
+        texts.push(text ?? key);
+      }
+
+      return texts;
+    }
+
+    return null;
+  }
+
+  /*
+   * What a name stands for, as lookup() finds it, and also through a file
+   * that only passes the name on (`export { X } from "./Copy"`, `export *
+   * from "./Copy"`), which the field lists never need.
+   */
+  private lookupValue(
+    parsed: ParsedFile,
+    name: string,
+    depth: number,
+  ): { parsed: ParsedFile; node: ts.Node } | null {
+    if (depth > MAX_DEPTH) {
+      return null;
+    }
+
+    const found: { parsed: ParsedFile; node: ts.Node } | null = this.lookup(
+      parsed,
+      name,
+      depth,
+    );
+
+    if (found) {
+      return found;
+    }
+
+    const passedOn: { file: string; exported: string } | undefined =
+      parsed.imports.get(name) || parsed.reexports.get(name);
+
+    if (passedOn) {
+      const target: ParsedFile | null = this.parse(passedOn.file);
+
+      return target && passedOn.exported !== "default"
+        ? this.lookupValue(target, passedOn.exported, depth + 1)
+        : null;
+    }
+
+    for (const file of parsed.reexportedFiles) {
+      const target: ParsedFile | null = this.parse(file);
+      const fromTarget: { parsed: ParsedFile; node: ts.Node } | null = target
+        ? this.lookupValue(target, name, depth + 1)
+        : null;
+
+      if (fromTarget) {
+        return fromTarget;
+      }
+    }
+
+    return null;
+  }
+
+  // The object literal an expression names: a constant, or a property of one.
+  private readObjectLiteral(
+    parsed: ParsedFile,
+    expression: ts.Node,
+    depth: number,
+  ): { parsed: ParsedFile; node: ts.ObjectLiteralExpression } | null {
+    if (depth > MAX_DEPTH) {
+      return null;
+    }
+
+    const node: ts.Node = unwrap(expression);
+
+    if (ts.isObjectLiteralExpression(node)) {
+      return { parsed, node };
+    }
+
+    if (ts.isIdentifier(node)) {
+      const declared: { parsed: ParsedFile; node: ts.Node } | null =
+        this.lookupValue(parsed, node.text, depth + 1);
+
+      return declared
+        ? this.readObjectLiteral(declared.parsed, declared.node, depth + 1)
+        : null;
+    }
+
+    if (ts.isPropertyAccessExpression(node)) {
+      const owner: {
+        parsed: ParsedFile;
+        node: ts.ObjectLiteralExpression;
+      } | null = this.readObjectLiteral(parsed, node.expression, depth + 1);
+      const value: ts.Expression | null = owner
+        ? propertyValueOf(owner.node, node.name.text)
+        : null;
+
+      return owner && value
+        ? this.readObjectLiteral(owner.parsed, value, depth + 1)
+        : null;
+    }
+
+    return null;
+  }
+}
+
+/*
+ * The value an object literal gives a property it names plainly (`name:`,
+ * `"name":`, or `name` alone, for a variable of that name). Null when it has
+ * none, or only under a computed name.
+ */
+function propertyValueOf(
+  object: ts.ObjectLiteralExpression,
+  name: string,
+): ts.Expression | null {
+  for (const property of object.properties) {
+    if (
+      ts.isPropertyAssignment(property) &&
+      (ts.isIdentifier(property.name) || ts.isStringLiteral(property.name)) &&
+      property.name.text === name
+    ) {
+      return property.initializer;
+    }
+
+    if (
+      ts.isShorthandPropertyAssignment(property) &&
+      property.name.text === name
+    ) {
+      return property.name;
+    }
+  }
+
+  return null;
 }
 
 // The hosts that draw a Create and an Edit form from one field list.
@@ -2309,6 +2677,17 @@ export function toRepositoryPath(
   return path.relative(repositoryRoot, filePath).split(path.sep).join("/");
 }
 
+/*
+ * The fewest forms a walk over the project may find before a guard trusts it
+ * (each guard's "are really read" test). It proves that the scanner reads the
+ * project, not how many forms there should be, so it sits far below the real
+ * count, as do the guards' other floors on what the walk finds: CI runs
+ * without ee/ (568 forms there on 2026-10-03, 581 with it), and the counts
+ * keep falling as forms are merged, folded into others or turned into
+ * switches that save on their own.
+ */
+export const MIN_SCANNED_FORMS: number = 250;
+
 export function scanFormFiles(data: {
   repositoryRoot: string;
   files: Array<string>;
@@ -2347,6 +2726,160 @@ export function isLongForm(form: FormFacts): boolean {
   return form.visibleFieldCount > LONG_FORM_FIELD_LIMIT;
 }
 
+/*
+ * "Forms of three rows or fewer fit on one page." The other side of the long
+ * form rule: a form short enough to take in at a glance has no stepper - no
+ * step list, no "Step 1 of 2", no Next between a name and the one editor it
+ * names. Three rows are one screen of a dialog; a fourth is where the long
+ * form rule starts asking for steps, so the two rules meet with no gap.
+ */
+export const SHORT_FORM_ROW_LIMIT: number = LONG_FORM_FIELD_LIMIT;
+
+/*
+ * The rows a list of fields takes on screen: countFieldRows, with a rule
+ * model's Match Criteria step drawn as what ModelForm puts there - one
+ * criteria builder, in place of the fields listed on it
+ * (RuleCriteriaModelForm) - so one row.
+ */
+function countScreenRows(
+  form: FormFacts,
+  fields: Array<FormFieldFacts>,
+): number {
+  if (!form.isRuleModel) {
+    return countFieldRows(fields);
+  }
+
+  const rows: Array<FormFieldFacts> = [];
+  let hasCriteriaBuilder: boolean = false;
+
+  for (const field of fields) {
+    if (field.stepId === RULE_CRITERIA_STEP_ID) {
+      if (hasCriteriaBuilder) {
+        continue;
+      }
+
+      hasCriteriaBuilder = true;
+      // The builder is drawn open, whatever section a listed field names.
+      rows.push({ ...field, collapsibleSection: undefined });
+      continue;
+    }
+
+    rows.push(field);
+  }
+
+  return countFieldRows(rows);
+}
+
+/*
+ * The rows the form shows: those of the longer of the forms its host draws
+ * (a table's Create and Edit forms apart, by doNotShowWhenCreating /
+ * doNotShowWhenEditing, each only when the table offers it), a folded
+ * section counting once and a rule's criteria builder counting once. A
+ * field shown under a condition counts: the form can be that long.
+ *
+ * Null for a table that draws no form at all - neither offered to create
+ * nor to edit - whose fields nobody ever sees.
+ */
+export function countFormRows(form: FormFacts): number | null {
+  const shown: Array<FormFieldFacts> = form.fields.filter(
+    (field: FormFieldFacts): boolean => {
+      return !field.isNeverShown;
+    },
+  );
+
+  if (!TABLE_HOSTS.has(form.host)) {
+    return countScreenRows(form, shown);
+  }
+
+  const drawsCreateForm: boolean = form.hasCreateForm !== false;
+
+  if (!drawsCreateForm && !form.hasEditForm) {
+    return null;
+  }
+
+  const onCreate: number = drawsCreateForm
+    ? countScreenRows(
+        form,
+        shown.filter((field: FormFieldFacts): boolean => {
+          return !field.isEditOnly;
+        }),
+      )
+    : 0;
+  const onEdit: number = form.hasEditForm
+    ? countScreenRows(
+        form,
+        shown.filter((field: FormFieldFacts): boolean => {
+          return !field.isCreateOnly;
+        }),
+      )
+    : 0;
+
+  return Math.max(onCreate, onEdit);
+}
+
+export interface ShortFormWithSteps {
+  form: FormFacts;
+  // The rows the form shows (countFormRows).
+  rows: number;
+  // What is wrong, and what to do about it.
+  message: string;
+}
+
+/*
+ * Forms that walk steps - a steps list, or a Summary step turned on, which
+ * makes BasicForm walk a default step and then the summary - although they
+ * show three rows or fewer. Only forms whose every field is followed are
+ * judged: a pass-through (fields handed in by a caller) is its callers' to
+ * answer for, and an uncountable form could be longer than it reads.
+ */
+export function findShortFormsWithSteps(
+  forms: Array<FormFacts>,
+): Array<ShortFormWithSteps> {
+  const found: Array<ShortFormWithSteps> = [];
+
+  for (const form of forms) {
+    if (
+      !form.hasSteps ||
+      form.isPassThrough ||
+      form.uncountableReasons.length > 0
+    ) {
+      continue;
+    }
+
+    const rows: number | null = countFormRows(form);
+
+    if (rows === null || rows > SHORT_FORM_ROW_LIMIT) {
+      continue;
+    }
+
+    const steps: string = form.hasSummaryOnly
+      ? "a Summary step"
+      : (form.steps || [])
+          .map((step: FormStepFacts): string => {
+            return step.id || "?";
+          })
+          .join(", ") || "?";
+
+    found.push({
+      form,
+      rows,
+      message: `${rows} rows walk steps (${steps}). Three rows fit on one page: drop the steps.`,
+    });
+  }
+
+  return found;
+}
+
+export function describeShortFormWithSteps(found: ShortFormWithSteps): string {
+  const titles: Array<string> = found.form.fields
+    .filter((field: FormFieldFacts): boolean => {
+      return !field.isNeverShown;
+    })
+    .map(describeFieldTitle);
+
+  return `${found.form.file}:${found.form.line} ${found.form.label} - ${found.message} Fields: ${titles.join(", ")}`;
+}
+
 // Forms of more than three fields with no steps, that are counted for sure.
 export function findLongFormsWithoutSteps(
   forms: Array<FormFacts>,
@@ -2361,6 +2894,38 @@ export function findLongFormsWithoutSteps(
   });
 }
 
+/*
+ * The one field the user can see when it is the only one, else null: the
+ * fields of the form less those never shown (registrations that only make
+ * ModelForm select a column). A field shown under a condition counts, so a
+ * form whose second field can appear is not a one-field form.
+ */
+export function getOnlyVisibleField(form: FormFacts): FormFieldFacts | null {
+  if (form.isPassThrough || form.uncountableReasons.length > 0) {
+    return null;
+  }
+
+  const shown: Array<FormFieldFacts> = form.fields.filter(
+    (field: FormFieldFacts): boolean => {
+      return !field.isNeverShown;
+    },
+  );
+
+  return shown.length === 1 ? shown[0]! : null;
+}
+
+/*
+ * A form that is one switch: the only field the user can see is a Toggle or
+ * a Checkbox. On a card (CardModelDetail) that is an Edit button, a dialog
+ * and a Save for one yes or no, which a ModelSwitchCard does in one press
+ * (OneSwitchCardsGuard).
+ */
+export function isOneSwitchForm(form: FormFacts): boolean {
+  const only: FormFieldFacts | null = getOnlyVisibleField(form);
+
+  return Boolean(only && isSwitchFieldType(only.fieldType));
+}
+
 // Forms without steps whose fields could not all be followed.
 export function findUncountableForms(
   forms: Array<FormFacts>,