@astryxdesign/cli 0.7.2-canary.fc12a18 → 0.7.2-canary.fdd384f

package/foundation/discovery/type-match.test.mjs

@@ -0,0 +1,169 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file A documented type judged against the type the code declares: a match
+ * or a mismatch only where both sides read exactly, else not compared.
+ */
+
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {createRequire} from 'node:module';
+import {afterAll, describe, expect, it} from 'vitest';
+import {judgeType} from './type-match.mjs';
+
+const ts = createRequire(import.meta.url)('typescript');
+const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-type-match-'));
+afterAll(() => fs.rmSync(dir, {recursive: true, force: true}));
+// React's types, as a global `React` namespace the way they declare it.
+const reactTypes = path.join(dir, 'node_modules', '@types', 'react');
+fs.mkdirSync(reactTypes, {recursive: true});
+fs.writeFileSync(
+  path.join(reactTypes, 'index.d.ts'),
+  'export = React;\nexport as namespace React;\ndeclare namespace React {\n  type Key = string | number | bigint;\n  interface KeyboardEvent<T = Element> { key: string; currentTarget: T }\n}\n',
+);
+
+/**
+ * Judges documented types against the props of `Props` in `source`.
+ * @param {string} source
+ * @returns {(prop: string, docType: string) => string}
+ */
+function judgeIn(source) {
+  const file = path.join(dir, 'props.ts');
+  fs.writeFileSync(file, source);
+  const program = ts.createProgram([file], {
+    strict: true,
+    noEmit: true,
+    typeRoots: [path.join(dir, 'node_modules', '@types')],
+    types: ['react'],
+  });
+  const checker = program.getTypeChecker();
+  const props = checker.getTypeAtLocation(
+    program
+      .getSourceFile(file)
+      .statements.find(
+        (/** @type {any} */ s) =>
+          ts.isInterfaceDeclaration(s) && s.name.text === 'Props',
+      ).name,
+  );
+  return (prop, docType) => {
+    const symbol = checker.getPropertyOfType(props, prop);
+    const declaration = symbol.valueDeclaration;
+    return judgeType(docType, [checker.getTypeOfSymbol(symbol)], {
+      ts,
+      checker,
+      location: declaration,
+      optional: (symbol.flags & ts.SymbolFlags.Optional) !== 0,
+      isDefaultLibrary: (/** @type {any} */ f) =>
+        program.isSourceFileDefaultLibrary(f),
+      written: [[declaration.type.getText()]],
+    });
+  };
+}
+
+describe('judgeType', () => {
+  it("judges exact parts in any order, names for them, a mutable array for a readonly one, an enum member beside its value, literals that hold `|` or `readonly`, `React.X` as React's own, and a member another covers, and compares no other form", () => {
+    const judge = judgeIn(`enum Color { Red = 'red', Blue = 'blue' }
+enum Hue { Red = 'red', Blue = 'blue' }
+enum Letter { A = 'a', B = 'b' }
+enum Odd { Lone = '\\uD800' }
+type Size = 'sm' | 'md';
+type Key = 'a' | 'b';
+export interface Props {
+  label: string;
+  size?: Size;
+  tags: readonly string[];
+  names: string[];
+  color: Color;
+  count: number | null;
+  onPick: (value: string) => void;
+  pair: 'a' | 'b';
+  letter: Letter | 'a' | 'b';
+  bracket: 'readonly[x';
+  onMode: (mode: 'readonly' | 'edit') => void;
+  onKey: (event: KeyboardEvent) => void;
+  onReactKey: (event: React.KeyboardEvent) => void;
+  rowKey: string | number | bigint;
+  pick: Key;
+  odd: Odd;
+  list: (string | number)[];
+  frozen: readonly (string | number)[];
+  bag: object;
+  nothing: void;
+}
+`);
+    expect(
+      [
+        ['label', 'string'],
+        ['label', 'number'],
+        ['size', "'md' | 'sm'"],
+        ['size', 'Size'],
+        ['size', "'sm'"],
+        ['size', "Size = 'sm'"],
+        ['tags', 'string[]'],
+        ['names', 'readonly string[]'],
+        ['color', 'Color'],
+        ['color', 'Hue'],
+        ['color', "'red' | 'blue'"],
+        ['count', 'number | null'],
+        ['count', 'number'],
+        ['onPick', '(value: string) => void'],
+        ['onPick', '() => void'],
+        ['pair', `"a'|'b"`],
+        ['pair', "Letter | 'a' | 'b'"],
+        ['letter', "'a' | 'b'"],
+        ['bracket', "'[x'"],
+        ['onMode', "(mode: 'edit' | 'readonly') => void"],
+        ['onKey', '(event: KeyboardEvent) => void'],
+        ['onKey', '(event: React.KeyboardEvent) => void'],
+        ['onReactKey', '(e: React.KeyboardEvent) => void'],
+        ['rowKey', 'React.Key'],
+        ['pick', 'Key'],
+        ['pick', 'React.Key'],
+        ['odd', 'Odd'],
+        ['odd', 'Odd | null'],
+        ['list', 'string[] | (string | number)[]'],
+        ['frozen', 'string[] | readonly (string | number)[]'],
+        ['list', 'readonly string[] | (string | number)[]'],
+        ['bag', 'object | string[]'],
+        ['nothing', 'void | undefined'],
+        ['label', 'any text'],
+      ].map(([prop, docType]) => `${prop}: ${docType} ${judge(prop, docType)}`),
+    ).toEqual([
+      'label: string match',
+      'label: number mismatch',
+      "size: 'md' | 'sm' match",
+      'size: Size match',
+      "size: 'sm' mismatch",
+      "size: Size = 'sm' match",
+      'tags: string[] match',
+      'names: readonly string[] mismatch',
+      'color: Color match',
+      'color: Hue mismatch',
+      "color: 'red' | 'blue' mismatch",
+      'count: number | null match',
+      'count: number mismatch',
+      'onPick: (value: string) => void match',
+      'onPick: () => void not_compared',
+      `pair: "a'|'b" mismatch`,
+      "pair: Letter | 'a' | 'b' match",
+      "letter: 'a' | 'b' match",
+      "bracket: '[x' mismatch",
+      "onMode: (mode: 'edit' | 'readonly') => void match",
+      'onKey: (event: KeyboardEvent) => void match',
+      'onKey: (event: React.KeyboardEvent) => void not_compared',
+      'onReactKey: (e: React.KeyboardEvent) => void match',
+      'rowKey: React.Key match',
+      'pick: Key match',
+      'pick: React.Key mismatch',
+      'odd: Odd match',
+      'odd: Odd | null mismatch',
+      'list: string[] | (string | number)[] match',
+      'frozen: string[] | readonly (string | number)[] match',
+      'list: readonly string[] | (string | number)[] mismatch',
+      'bag: object | string[] match',
+      'nothing: void | undefined match',
+      'label: any text not_compared',
+    ]);
+  });
+});

package/foundation/discovery/type-text.d.mts

@@ -0,0 +1,68 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Why the project's TypeScript is too old for this module (before 4.8, the
+ * oldest every printed form is tested on), or null.
+ * @param {{version?: string}} ts
+ * @returns {string | null}
+ */
+export function typeTextTooOld(ts: {
+    version?: string;
+}): string | null;
+/**
+ * Canonical type text: the members of the type's top-level union, sorted.
+ * The result is cached and frozen, so no caller can change it for the next.
+ * @param {string} text
+ * @param {{ts: any, optional?: boolean}} options `ts` is the project's own
+ *   `typescript`; with `optional`, `undefined` is dropped, as an optional
+ *   prop takes it anyway
+ * @returns {readonly string[]}
+ */
+export function normalizeTypeText(text: string, options: {
+    ts: any;
+    optional?: boolean;
+}): readonly string[];
+/**
+ * @file Loose comparison of TypeScript type text, for checking a documented
+ * prop type against the type its source declares.
+ *
+ * {@link normalizeTypeText} parses the text with the project's own TypeScript
+ * and prints the type canonically, so grouping always comes from the parse.
+ * Two texts are the same type here when they print the same. The printer
+ * merges only what TypeScript reads as one type:
+ * - comments, whitespace, parentheses that change nothing, and quote style;
+ * - the names of function and tuple parameters (a `this` parameter is kept,
+ *   and a type predicate names its parameter by place);
+ * - the order of a union's members and of an object type's properties;
+ * - `Array<T>` and `T[]`; a `React.` qualifier;
+ * - `true | false` and `boolean`; a string, number or boolean literal beside
+ *   its primitive; `never` among other union members; and `undefined` on an
+ *   optional prop.
+ * It also sets `readonly`, `Readonly<…>` and `ReadonlyArray<…>` aside: the
+ * prop type judgment compares text that writes `readonly` exactly instead.
+ * Below the top of a type, a function or conditional type is always printed
+ * in parentheses, and a union or intersection wherever its members would
+ * otherwise bind differently. Any form the printer does not know is kept as
+ * written (comments and whitespace aside), so it never reads as another
+ * type. Text that does not parse as one type comes back marked with
+ * {@link UNPARSED}, which no printed type starts with, so it never matches.
+ * {@link typeTextTooOld} says when the project's TypeScript is too old to
+ * read type text with.
+ *
+ * @input Type text as written in a doc or a source file, or printed by the
+ *   TypeScript compiler, and the project's own `typescript`.
+ * @output The canonical members of the type's top-level union, sorted.
+ * @position Used by the prop type judgment (type-match.mjs).
+ */
+/** Marks text that does not parse as one type: no printed type has it. */
+export const UNPARSED: "\0";
+export type Printed = {
+    text: string;
+    level: number;
+    /**
+     * a literal
+     * its primitive absorbs in a union
+     */
+    literal?: "string" | "number" | "boolean" | "other" | undefined;
+};