@astryxdesign/cli 0.7.2-canary.e2909cf → 0.7.2-canary.e4bdd70

package/foundation/discovery/package-tsconfig.mjs

@@ -0,0 +1,228 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Read a package's TypeScript project the way `tsc` reads it, so a
+ * check that reads the package's types with its own compiler sees what the
+ * package compiles against.
+ *
+ * - The config is the nearest `tsconfig.json`: the package's own, or a
+ *   monorepo's root config for a local package. An app's config above an
+ *   installed package (one below `node_modules`) is not the package's, and is
+ *   not read.
+ * - A solution-style config (`"files": []` with `references`) lends the
+ *   referenced config, at any depth, that includes the files to read.
+ * - The declaration files the config includes, included files that declare
+ *   globals or augment a module, and included scripts (no import or export)
+ *   join the files to read, so ambient types resolve as `tsc` resolves them.
+ * - Without a config, defaults read TSX the way bundlers do. A config with
+ *   errors is reported, never read as defaults.
+ *
+ * @input The project's own `typescript`, the package directory, and the
+ *   source files to read.
+ * @output Compiler options, the declaration files to add, and the config's
+ *   error, if any.
+ * @position Foundation discovery, used by the documented-props comparison.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/**
+ * Whether a file the config includes declares types every file sees: a
+ * declaration file, a file that declares globals or augments a module, or a
+ * script (a `.ts` file that TypeScript reads as no module).
+ * @param {any} ts
+ * @param {string} file
+ */
+function isAmbient(ts, file) {
+  if (/\.d\.[cm]?ts$/.test(file)) return true;
+  let text;
+  try {
+    text = fs.readFileSync(file, 'utf8');
+  } catch {
+    return false;
+  }
+  if (/\bdeclare\s+(?:global|module)\b/.test(text)) return true;
+  if (!/\.tsx?$/.test(file)) return false;
+  // Without the words, no module; with them, TypeScript decides.
+  return (
+    !/\b(?:import|export)\b/.test(text) ||
+    !ts.isExternalModule(
+      ts.createSourceFile(file, text, ts.ScriptTarget.Latest),
+    )
+  );
+}
+
+/**
+ * Read a config's `files` entries as `tsc` does, and report the first it
+ * cannot find. TypeScript itself substitutes `${configDir}` (on a version
+ * that has it), resolves each entry against the config that writes it, and
+ * tries the TypeScript extensions for one written without its own, so this
+ * cannot drift from `tsc`. The parsed file names then hold the files found.
+ * A file the `include` matched that is gone by the time it is read was
+ * another process's, and is not checked here.
+ * @param {any} ts
+ * @param {any} raw the config's JSON
+ * @param {string} configPath
+ * @param {any} config the parsed config, whose file names are updated
+ * @returns {string | null} the message `tsc` gives for the first entry it
+ *   cannot find (TS6053, or TS6231 for a folder)
+ */
+function readFilesEntries(ts, raw, configPath, config) {
+  const literal = ts.parseJsonConfigFileContent(
+    raw,
+    {...ts.sys, readDirectory: () => []},
+    path.dirname(configPath),
+    undefined,
+    configPath,
+  ).fileNames;
+  if (literal.length === 0 || typeof ts.createProgram !== 'function') {
+    return null;
+  }
+  // Only the entries themselves: no library, no types, no imports.
+  const program = ts.createProgram({
+    rootNames: literal,
+    options: {
+      ...config.options,
+      noLib: true,
+      noResolve: true,
+      types: [],
+      noEmit: true,
+    },
+  });
+  const missing = program
+    .getOptionsDiagnostics()
+    .find(/** @param {any} d */ d => d.code === 6053 || d.code === 6231);
+  if (missing) {
+    const text = missing.messageText;
+    return typeof text === 'string' ? text : text.messageText;
+  }
+  const entries = new Set(
+    literal.map(/** @param {string} f */ f => path.resolve(f)),
+  );
+  config.fileNames = [
+    ...config.fileNames.filter(
+      /** @param {string} f */ f => !entries.has(path.resolve(f)),
+    ),
+    ...program.getSourceFiles().map(/** @param {any} sf */ sf => sf.fileName),
+  ];
+  return null;
+}
+
+/**
+ * @param {any} ts the project's own `typescript`
+ * @param {string} packageDir
+ * @param {string[]} sources the files to read
+ * @returns {{options: any, declarations: string[], error?: string}}
+ */
+export function readPackageTsconfig(ts, packageDir, sources) {
+  const defaults = {
+    jsx: ts.JsxEmit.ReactJSX,
+    target: ts.ScriptTarget.ES2022,
+    module: ts.ModuleKind.ESNext,
+    moduleResolution: ts.ModuleResolutionKind.Bundler,
+    strict: true,
+    allowJs: true,
+    esModuleInterop: true,
+    resolveJsonModule: true,
+    allowImportingTsExtensions: true,
+  };
+  /** @type {string | undefined} */
+  let error;
+  /** @type {(configPath: string) => any} */
+  const parse = configPath => {
+    const read = ts.readConfigFile(configPath, ts.sys.readFile);
+    const config = read.error
+      ? {errors: [read.error], fileNames: [], options: {}}
+      : ts.parseJsonConfigFileContent(
+          read.config,
+          ts.sys,
+          path.dirname(configPath),
+          undefined,
+          configPath,
+        );
+    // "No inputs were found" is how a solution-style config reads.
+    const problem = config.errors.find(
+      /** @param {any} d */ d => d.code !== 18003,
+    );
+    const where = path.relative(packageDir, configPath);
+    if (problem) {
+      config.error = `${where}: ${ts.flattenDiagnosticMessageText(problem.messageText, ' ')}`;
+    } else if (!read.error) {
+      const missing = readFilesEntries(ts, read.config, configPath, config);
+      if (missing) {
+        // Paths read from the package, as the config's other errors are.
+        const dir = path.dirname(configPath).split(path.sep).join('/');
+        const rel = path.relative(packageDir, path.dirname(configPath));
+        config.error = `${where}: ${missing
+          .split(`${dir}/`)
+          .join(rel ? `${rel.split(path.sep).join('/')}/` : '')}`;
+      }
+    }
+    return config;
+  };
+  /** @type {any} */
+  let parsed;
+  try {
+    const found = ts.findConfigFile(
+      packageDir,
+      ts.sys.fileExists,
+      'tsconfig.json',
+    );
+    // A config above the package is an app's when the package is installed
+    // below it (`node_modules`), and the package's own otherwise (a
+    // monorepo's root config, as `tsc` reads it).
+    const installed =
+      found &&
+      path
+        .relative(path.dirname(found), packageDir)
+        .split(path.sep)
+        .includes('node_modules');
+    parsed = found && !installed ? parse(found) : null;
+    const own = new Set(sources.map(file => path.resolve(file)));
+    /** @type {(config: any) => boolean} */
+    const includes = config =>
+      config.fileNames.some(
+        /** @param {string} file */ file => own.has(path.resolve(file)),
+      );
+    // Every reference, at any depth, each config once (a cycle ends). One
+    // that is missing or doesn't parse is the project's error when no config
+    // includes the sources, as `tsc` reports it.
+    const visited = new Set(found ? [path.resolve(found)] : []);
+    /** @type {any} */
+    let broken = null;
+    /** @type {(config: any) => any} */
+    const including = config => {
+      if (includes(config)) return config;
+      for (const ref of config.projectReferences ?? []) {
+        const next = path.resolve(ts.resolveProjectReferencePath(ref));
+        if (visited.has(next)) continue;
+        visited.add(next);
+        const referenced = parse(next);
+        if (referenced.error) broken ??= referenced;
+        const hit = including(referenced);
+        if (hit) return hit;
+      }
+      return null;
+    };
+    if (parsed) parsed = including(parsed) ?? broken ?? parsed;
+  } catch {
+    parsed = null;
+  }
+  error = parsed?.error;
+  const options = parsed ? {...parsed.options} : defaults;
+  if (options.jsx == null) options.jsx = defaults.jsx;
+  return {
+    options: {
+      ...options,
+      noEmit: true,
+      skipLibCheck: true,
+      incremental: false,
+      composite: false,
+    },
+    ...(error ? {error} : {}),
+    declarations: (parsed?.fileNames ?? []).filter(
+      /** @param {string} file */ file => isAmbient(ts, file),
+    ),
+  };
+}

package/foundation/discovery/package-tsconfig.test.mjs

@@ -0,0 +1,210 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file readPackageTsconfig(): the package's own config, a solution-style
+ * config's references, a monorepo root's config for a local package but not
+ * an app's above an installed one, ambient declaration files, and a config
+ * with errors.
+ */
+
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {createRequire} from 'node:module';
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import {readPackageTsconfig} from './package-tsconfig.mjs';
+
+const require = createRequire(import.meta.url);
+const ts = require('typescript');
+
+/** @type {string} */
+let root;
+
+beforeEach(() => {
+  root = fs.realpathSync(
+    fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-tsconfig-')),
+  );
+});
+
+afterEach(() => {
+  fs.rmSync(root, {recursive: true, force: true});
+});
+
+/**
+ * @param {string} rel
+ * @param {string | object} content
+ */
+function write(rel, content) {
+  const file = path.join(root, rel);
+  fs.mkdirSync(path.dirname(file), {recursive: true});
+  fs.writeFileSync(
+    file,
+    typeof content === 'string' ? content : JSON.stringify(content),
+  );
+  return file;
+}
+
+const OPTIONS = {strict: true, jsx: 'react-jsx', paths: {'@/*': ['./src/*']}};
+
+describe('readPackageTsconfig', () => {
+  it('reads defaults without a config, and the config the package has, with the declaration files it includes', () => {
+    const source = write('src/Button.tsx', 'export {};\n');
+    const defaults = readPackageTsconfig(ts, root, [source]);
+    expect(defaults.options).toMatchObject({
+      jsx: ts.JsxEmit.ReactJSX,
+      strict: true,
+      noEmit: true,
+    });
+    expect(defaults.declarations).toEqual([]);
+    expect(defaults.error).toBeUndefined();
+
+    write('tsconfig.json', {
+      compilerOptions: OPTIONS,
+      include: ['src', 'types'],
+    });
+    const ambient = write('types/ambient.d.ts', 'interface A {}\n');
+    const global = write('src/global.ts', 'declare global {}\nexport {};\n');
+    // A script (no import or export) declares globals too, an `export`
+    // inside its namespace included.
+    const script = write('types/props.ts', 'interface ScriptProps {}\n');
+    const namespace = write(
+      'types/acme.ts',
+      'declare namespace Acme {\n  export interface Props {}\n}\n',
+    );
+    write('src/module.ts', 'export interface ModuleProps {}\n');
+
+    const own = readPackageTsconfig(ts, root, [source]);
+
+    expect(own.options.paths).toEqual(OPTIONS.paths);
+    expect(own.declarations.sort()).toEqual(
+      [global, ambient, script, namespace].sort(),
+    );
+  });
+
+  it("follows a solution-style config's references, at any depth and through a cycle, to the config that includes the sources", () => {
+    const source = write('src/Button.tsx', 'export {};\n');
+    const chain = [
+      'tsconfig.json',
+      'l1.json',
+      'l2.json',
+      'l3.json',
+      'l4.json',
+      'l5.json',
+    ];
+    chain.forEach((file, i) =>
+      write(file, {
+        files: [],
+        // Each level also refers back to the root, a cycle tsc rejects but
+        // the walk must not loop on.
+        references: [
+          {path: `./${chain[i + 1] ?? 'app.json'}`},
+          {path: './tsconfig.json'},
+        ],
+      }),
+    );
+    write('app.json', {compilerOptions: OPTIONS, include: ['src']});
+
+    const project = readPackageTsconfig(ts, root, [source]);
+
+    expect(project.error).toBeUndefined();
+    expect(project.options.paths).toEqual(OPTIONS.paths);
+
+    // A reference that is missing or doesn't parse, when no config includes
+    // the sources, is the project's error, as `tsc` reports it.
+    write('tsconfig.json', {files: [], references: [{path: './gone.json'}]});
+    expect(readPackageTsconfig(ts, root, [source]).error).toMatch(
+      /^gone\.json: .*gone\.json/,
+    );
+    write('broken.json', '{"compilerOptions": ');
+    write('tsconfig.json', {files: [], references: [{path: './broken.json'}]});
+    expect(readPackageTsconfig(ts, root, [source]).error).toMatch(
+      /^broken\.json: /,
+    );
+  });
+
+  it("reads a monorepo root's config for a local package, and not an app's config for a package installed below it", () => {
+    write('tsconfig.json', {compilerOptions: OPTIONS});
+    const local = path.join(root, 'packages', 'local');
+    const installed = path.join(root, 'node_modules', '@acme', 'widgets');
+    const localSource = write('packages/local/src/Button.tsx', 'export {};\n');
+    const installedSource = write(
+      'node_modules/@acme/widgets/src/Button.tsx',
+      'export {};\n',
+    );
+
+    expect(readPackageTsconfig(ts, local, [localSource]).options.paths).toEqual(
+      OPTIONS.paths,
+    );
+    expect(
+      readPackageTsconfig(ts, installed, [installedSource]).options.paths,
+    ).toBeUndefined();
+  });
+
+  it('reports a config with errors instead of reading defaults', () => {
+    const source = write('src/Button.tsx', 'export {};\n');
+    write('tsconfig.json', {files: ['src/Button.tsx', 'src/missing.ts']});
+    expect(readPackageTsconfig(ts, root, [source]).error).toMatch(
+      /^tsconfig\.json: .*src\/missing\.ts.* not found/,
+    );
+
+    write('tsconfig.json', {extends: './missing-base.json'});
+    expect(readPackageTsconfig(ts, root, [source]).error).toMatch(
+      /^tsconfig\.json: .*missing-base\.json/,
+    );
+
+    write('tsconfig.json', '{"compilerOptions": ');
+    expect(readPackageTsconfig(ts, root, [source]).error).toMatch(
+      /^tsconfig\.json: /,
+    );
+  });
+
+  it('reads each `files` entry as `tsc` finds it', () => {
+    const source = write('src/Button.tsx', 'export {};\n');
+    write('src/Card.ts', 'export {};\n');
+    write('types/globals.ts', 'interface AcmeGlobal { tone?: string }\n');
+    write('configs/base.json', {files: ['${configDir}/src/Button.tsx']});
+    /** @type {(config: object) => any} */
+    const read = config => {
+      write('tsconfig.json', {compilerOptions: OPTIONS, ...config});
+      return readPackageTsconfig(ts, root, [source]);
+    };
+
+    // `${configDir}`, written in the package's config or in a shared base it
+    // extends, and an entry without its extension compile with `tsc -p`.
+    expect(
+      read({files: ['${configDir}/src/Button.tsx']}).error,
+    ).toBeUndefined();
+    expect(read({extends: './configs/base.json'}).error).toBeUndefined();
+    const bare = read({files: ['src/Button', 'src/Card', 'types/globals']});
+    expect(bare.error).toBeUndefined();
+    expect(bare.declarations).toEqual([path.join(root, 'types', 'globals.ts')]);
+
+    // An entry `tsc` can't find is an error: a missing file (TS6053), and a
+    // folder (TS6231).
+    expect(read({files: ['src/Button.tsx', 'src/gone.ts']}).error).toMatch(
+      /^tsconfig\.json: File 'src\/gone\.ts' not found\.$/,
+    );
+    expect(read({files: ['src']}).error).toMatch(
+      /^tsconfig\.json: Could not resolve the path 'src' with the extensions/,
+    );
+  });
+
+  it('reports only a missing `files` entry, not a file the `include` matched that is gone by the time it is read', () => {
+    const source = write('src/Button.tsx', 'export {};\n');
+    write('tsconfig.json', {compilerOptions: OPTIONS, include: ['src']});
+    // A file another process writes and removes while the config is read.
+    const gone = path.join(root, 'src', 'gone.ts');
+    const racing = {
+      ...ts,
+      sys: {
+        ...ts.sys,
+        readDirectory: (/** @type {any[]} */ ...args) => [
+          ...ts.sys.readDirectory(...args),
+          gone,
+        ],
+      },
+    };
+
+    expect(readPackageTsconfig(racing, root, [source]).error).toBeUndefined();
+  });
+});

package/foundation/discovery/project-typescript.d.mts

@@ -0,0 +1,23 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Resolve the project's own `typescript`, trying each directory in order.
+ * @param {Array<string | null | undefined>} dirs
+ * @returns {{ts: any, version: string} | {ts: null, version: string} | null}
+ *   `ts: null` when a TypeScript is installed but has no `createProgram`
+ */
+export function resolveProjectTypeScript(dirs: Array<string | null | undefined>): {
+    ts: any;
+    version: string;
+} | {
+    ts: null;
+    version: string;
+} | null;
+/**
+ * Why a check that needs the compiler did not run, when the TypeScript
+ * installed has no JavaScript compiler API.
+ * @param {string} version
+ * @param {string} outcome what was not done, such as `docs were not checked`
+ */
+export function unusableTypeScriptReason(version: string, outcome: string): string;

package/foundation/discovery/project-typescript.mjs

@@ -0,0 +1,61 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Find the project's own TypeScript compiler.
+ *
+ * @input Directories to resolve `typescript` from, in order.
+ * @output The compiler module and its version; or, when the only TypeScript
+ *   installed has no JavaScript compiler API to read types with, its version
+ *   alone; or null when none is installed.
+ * @position Shared by the author checks that read source with the project's
+ *   compiler, so each finds it, and says why it cannot use it, the same way.
+ */
+
+import * as path from 'node:path';
+import {createRequire} from 'node:module';
+
+/**
+ * Resolve the project's own `typescript`, trying each directory in order.
+ * @param {Array<string | null | undefined>} dirs
+ * @returns {{ts: any, version: string} | {ts: null, version: string} | null}
+ *   `ts: null` when a TypeScript is installed but has no `createProgram`
+ */
+export function resolveProjectTypeScript(dirs) {
+  /** @type {string | null} */
+  let unusable = null;
+  for (const dir of dirs) {
+    if (!dir) continue;
+    const require = createRequire(path.join(path.resolve(dir), 'package.json'));
+    /** The version of the `typescript` package installed here, or null. */
+    const installed = () => {
+      try {
+        const {version} = require('typescript/package.json');
+        return typeof version === 'string' && version !== '' ? version : null;
+      } catch {
+        return null;
+      }
+    };
+    try {
+      const ts = require('typescript');
+      if (ts && typeof ts.createProgram === 'function') {
+        return {ts, version: String(ts.version)};
+      }
+      unusable ??= installed();
+    } catch {
+      // Not installed from here, or installed without an entry this CLI can
+      // load; try the next directory.
+      unusable ??= installed();
+    }
+  }
+  return unusable ? {ts: null, version: unusable} : null;
+}
+
+/**
+ * Why a check that needs the compiler did not run, when the TypeScript
+ * installed has no JavaScript compiler API.
+ * @param {string} version
+ * @param {string} outcome what was not done, such as `docs were not checked`
+ */
+export function unusableTypeScriptReason(version, outcome) {
+  return `TypeScript ${version} is installed in this project, but it has no JavaScript compiler API (\`createProgram\`) to read types with, so ${outcome}.`;
+}