@aoelite/refpact-ts 0.0.0-stage → 0.2.0

package/dist/frontend/native.d.ts

@@ -0,0 +1,3 @@
+import type { Backend, Installed } from "./compiler.ts";
+/** Loads the client of the installed TypeScript 7. */
+export declare function loadNative(installed: Installed): Promise<Backend>;

package/dist/frontend/native.js

@@ -0,0 +1,165 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+/** Loads the client of the installed TypeScript 7. */
+export async function loadNative(installed) {
+    const is71 = "./sync" in installed.exports;
+    const entry = is71 ? installed.packageName : `${installed.packageName}/unstable`;
+    // The numbers of the kinds differ between 7.0 and 7.1, so the value must be the loaded one.
+    const ast = (await import(__rewriteRelativeImportExtension(`${entry}/ast`)));
+    const sync = (await import(__rewriteRelativeImportExtension(`${entry}/sync`)));
+    const useOS = is71 ? (await import(__rewriteRelativeImportExtension(`${entry}/fs`))).serverFS.useOS : undefined;
+    const client = { is71, API: sync.API, SymbolFlags: sync.SymbolFlags, useOS };
+    return {
+        SyntaxKind: ast.SyntaxKind,
+        jsDocBesideChildren: false,
+        openProjects: (root, configFiles, files) => openProjects(client, root, configFiles, files),
+    };
+}
+/** Opens the given tsconfig files in one compiler process. */
+function openProjects(client, root, configFiles, files) {
+    // With a file system, the compiler asks this process for each file that it reads.
+    const api = new client.API(files !== undefined ? { cwd: root, fs: fileSystem(client, files) } : { cwd: root });
+    let snapshot;
+    try {
+        let project;
+        if (client.is71) {
+            const opened = api.createSnapshot({ openProjects: [...configFiles] });
+            snapshot = opened;
+            project = (configFile) => {
+                const found = opened.getConfiguredProject(configFile);
+                return found && { program: found.program, checker: found.checker, options: found.parsedCommandLine.options };
+            };
+        }
+        else {
+            const opened = api.updateSnapshot({ openProjects: [...configFiles] });
+            snapshot = opened;
+            project = (configFile) => {
+                const found = opened.getProject(configFile);
+                return found && { program: found.program, checker: found.checker, options: found.compilerOptions };
+            };
+        }
+        const projects = configFiles.map((configFile) => {
+            const found = project(configFile);
+            if (found === undefined) {
+                throw new Error(`refpact: the TypeScript compiler did not load ${configFile}`);
+            }
+            return wrap(client, configFile, found, () => api.clearSourceFileCache());
+        });
+        const opened = snapshot;
+        return {
+            projects,
+            close() {
+                opened.dispose();
+                api.close();
+            },
+        };
+    }
+    catch (error) {
+        snapshot?.dispose();
+        api.close();
+        throw error;
+    }
+}
+/**
+ * The callbacks of the file system in the form of the client. In 7.0 a callback that is
+ * left out, or that gives `undefined`, lets the compiler read the disk. In 7.1 each callback
+ * must be there, and a value of the client says the same.
+ */
+function fileSystem(client, files) {
+    if (!client.is71) {
+        return files;
+    }
+    const useOS = client.useOS;
+    return {
+        readFile: (fileName) => files.readFile(fileName) ?? useOS,
+        fileExists: (fileName) => files.fileExists(fileName) ?? useOS,
+        getAccessibleEntries(directoryName) {
+            const entries = files.getAccessibleEntries(directoryName);
+            return entries === undefined ? useOS : { ...entries, symlinks: undefined };
+        },
+        // A component file is shown as a plain file.
+        stat: (fileName) => {
+            const text = files.readFile(fileName);
+            return text === undefined ? useOS : { mode: 0o100644, size: text.length, mtime: new Date(0) };
+        },
+        directoryExists: useOS,
+        realpath: useOS,
+        writeFile: useOS,
+        removeFile: useOS,
+    };
+}
+function wrap(client, configFile, { program, checker, options }, forget) {
+    // TypeScript 7 removed `baseUrl` (error TS5102) and does not resolve with it. A project
+    // that sets it would be read with those imports seen as packages, and rules on the files
+    // would pass without a check.
+    if (options.baseUrl !== undefined) {
+        throw new Error(`refpact: ${configFile} sets baseUrl, which TypeScript 7 removed. Use \`paths\` instead.`);
+    }
+    const ownFiles = program.getSourceFileNames().filter((file) => {
+        const metadata = program.getSourceFileMetadata(file);
+        return metadata !== undefined && !metadata.isDefaultLibrary && !metadata.isFromExternalLibrary;
+    });
+    // Each answer of the compiler is a round trip to another process, so each is kept. Many
+    // files import the same module, and many names lead through the same re-export.
+    const aliases = new Map();
+    const exports = new Map();
+    const owners = new Map();
+    const Flags = client.SymbolFlags;
+    const memberFlags = Flags.Property | Flags.Method | Flags.GetAccessor | Flags.SetAccessor | Flags.EnumMember;
+    const ownerFlags = Flags.Class | Flags.Interface | Flags.RegularEnum | Flags.ConstEnum;
+    return {
+        configFile,
+        options: options,
+        ownFiles,
+        sourceFile: (file) => program.getSourceFile(file),
+        forgetSourceFiles: forget,
+        symbolsAt: (nodes) => (nodes.length === 0 ? [] : checker.getSymbolAtLocation(nodes)),
+        shorthandValueAt: (property) => checker.getShorthandAssignmentValueSymbol(property),
+        filesOf: (symbol) => symbol.declarations.map((declaration) => declaration.path),
+        same: (a, b) => a.id === b.id,
+        ownerOf(given) {
+            const symbol = given;
+            if ((symbol.flags & memberFlags) === 0) {
+                return undefined;
+            }
+            if (owners.has(symbol.id)) {
+                return owners.get(symbol.id);
+            }
+            const parent = symbol.getParent();
+            const found = parent !== undefined && (parent.flags & ownerFlags) !== 0 ? parent : undefined;
+            owners.set(symbol.id, found);
+            return found;
+        },
+        isTypeParameter: (symbol) => (symbol.flags & Flags.TypeParameter) !== 0,
+        immediateAlias(given) {
+            const symbol = given;
+            // The compiler stops with a panic when it is asked for the target of a symbol that
+            // is not an alias, so the flag is checked first.
+            if ((symbol.flags & client.SymbolFlags.Alias) === 0) {
+                return undefined;
+            }
+            if (aliases.has(symbol.id)) {
+                return aliases.get(symbol.id);
+            }
+            const target = checker.getImmediateAliasedSymbol(symbol);
+            const found = target === undefined || checker.isUnknownSymbol(target) ? undefined : target;
+            aliases.set(symbol.id, found);
+            return found;
+        },
+        exportsOf(given) {
+            const module = given;
+            let found = exports.get(module.id);
+            if (found === undefined) {
+                found = new Map(checker.getExportsOfModule(module).map((symbol) => [symbol.name, symbol]));
+                exports.set(module.id, found);
+            }
+            return found;
+        },
+    };
+}

package/dist/frontend/paths.d.ts

@@ -0,0 +1,10 @@
+export declare function exportSegment(name: string): string;
+export declare function packageSegment(name: string): string;
+export declare function globalSegment(name: string): string;
+export declare function nodeSegment(name: string): string;
+/**
+ * How reports print these paths, the way an import names them: `src/db/client.ts#query`,
+ * `lodash/fp#map`. An export joins without a separator, and a package loses `npm:`.
+ */
+export declare const ATTACHED_PREFIXES: readonly string[];
+export declare const HIDDEN_PREFIXES: readonly string[];

package/dist/frontend/paths.js

@@ -0,0 +1,18 @@
+export function exportSegment(name) {
+    return `#${name}`;
+}
+export function packageSegment(name) {
+    return `npm:${name}`;
+}
+export function globalSegment(name) {
+    return `global:${name}`;
+}
+export function nodeSegment(name) {
+    return `node:${name}`;
+}
+/**
+ * How reports print these paths, the way an import names them: `src/db/client.ts#query`,
+ * `lodash/fp#map`. An export joins without a separator, and a package loses `npm:`.
+ */
+export const ATTACHED_PREFIXES = ["#"];
+export const HIDDEN_PREFIXES = ["npm:"];

package/dist/frontend/project.d.ts

@@ -0,0 +1,118 @@
+import type { FactSet } from "../core/index.ts";
+import type { ComponentExtension } from "./components.ts";
+/** Options of {@link loadProject}. */
+export interface LoadOptions {
+    /**
+     * The directory that file paths in rules are relative to. Files outside it are not units.
+     * Default: the directory of the first tsconfig file.
+     */
+    readonly root?: string;
+    /**
+     * Resolves what `object.name` names when the object is a value: a member of a class, of an
+     * interface or of an enum of the project. Each such use in another file is a reference of
+     * the kind `member` to `file.ts#Owner#name`, so that `order.total()` is a use of
+     * `src/domain/order.ts#Order#total`.
+     *
+     * The load then reads every function body and asks the compiler about each access, which
+     * takes longer. Default: `false`.
+     */
+    readonly resolveMembers?: boolean;
+    /**
+     * Lets a use of a member of an interface or of a class also count as a use of the same
+     * member of each class of the project that implements or extends it. `store.save(order)`,
+     * where `store` is a `Store`, is then also a **candidate** use of `PgStore#save`, because
+     * the call can run it. A rule about what the code can reach, such as `mustNotReach`, then
+     * follows the call into the classes.
+     *
+     * This turns on {@link LoadOptions.resolveMembers}. It is not the default, because it
+     * turns around what an interface is for: with it, the code that calls the interface uses
+     * the files that implement it. A rule leaves the candidates out with
+     * `ignoringCandidates()`. Default: `false`.
+     */
+    readonly followImplementations?: boolean;
+    /**
+     * Reads the code of component files: `.svelte`, `.vue` and `.astro`. `true` reads all
+     * three, and a list names the extensions to read.
+     *
+     * Each component file is a file of the project under its own name, `src/App.svelte`. Its
+     * code is what its `<script>` blocks hold, and for Astro also the part between the `---`
+     * lines at its start. The imports and the globals of that code are references as in a
+     * TypeScript file, at their lines and columns in the component, and an import of
+     * `./App.svelte` leads to the component.
+     *
+     * The markup is not read: a global or a member that only the markup uses is not seen. A
+     * component that the markup uses is imported in the script, so no import is missed.
+     *
+     * The compiler then asks refpact for each file that it reads, which makes the load
+     * slower. Default: `false`.
+     */
+    readonly components?: boolean | readonly ComponentExtension[];
+    /**
+     * Reads the dependencies that the `package.json` files name, and the packages that those
+     * need.
+     *
+     * The code shows which packages a file imports. A `package.json` shows which packages are
+     * installed, also those that no code imports. With this option, each `package.json` that a
+     * file of the project belongs to is a file of the project under its path, `package.json`
+     * or `packages/app/package.json`, and each dependency is a reference from it to the
+     * package, at the line of its key:
+     *
+     * - `dependency`, `dev-dependency`, `peer-dependency` and `optional-dependency` for what
+     *   the file names. A package that another `package.json` of the project declares is also
+     *   a reference to that file, so the rules about files, such as `mustBeAcyclic`, see the
+     *   dependencies between the packages of a monorepo.
+     * - `transitive-dependency` for each other package that a dependency needs, with the
+     *   packages on the way in the note of the violation, and `transitive-dev-dependency`
+     *   when only the `devDependencies` need it. They are found in the `node_modules`
+     *   directories, as Node finds them; a package that is not installed is not followed.
+     *
+     * A `package.json` with a name declares one item of the kind `package`.
+     *
+     * ```ts
+     * const app = loadProject("tsconfig.json", { readDependencies: true });
+     * rule("the app is installed without lodash")
+     *   .files(anyOf("package.json"))
+     *   .mustNotImport(anyOf(pkg("lodash")))
+     *   .onlyKinds("dependency", "transitive-dependency")
+     *   .check(app);
+     * ```
+     *
+     * `mustOnlyImportDeclaredPackages` and `mustNotImportDevDependencies` need this option.
+     *
+     * Each of these references has the version and the licence of the installed package as
+     * `properties`, for a check of your own: `seen.reference.properties?.["license"]`. Name
+     * them in the rule, with `readingProperties`.
+     *
+     * It is not the default: a `package.json` is then a file that `all()` selects, so a rule
+     * with a list of what the files may import would have to name every package, and a rule
+     * such as `mustBeImported` would have to leave the file out. The load reads the
+     * `package.json` of each installed package that the dependencies lead to. Default: `false`.
+     */
+    readonly readDependencies?: boolean;
+}
+/** One or more analysed TypeScript projects. */
+export declare class Project {
+    /** The directory that file paths are relative to. */
+    readonly root: string;
+    /** The tsconfig files that were loaded, also those found through `references`. */
+    readonly configFiles: readonly string[];
+    /** The facts, for the core. */
+    readonly facts: FactSet;
+    /** @internal */
+    constructor(root: string, configFiles: readonly string[], facts: FactSet);
+    /** The paths of all files, relative to the root, such as `src/app/main.ts`. */
+    get files(): string[];
+}
+/**
+ * Loads the project of a tsconfig file, and the projects it names in `references`. A
+ * directory stands for its `tsconfig.json`, or for its `jsconfig.json` when it has none. A
+ * directory with neither is read with default options: all its files below it except
+ * `node_modules`, JavaScript too, with the resolution of a bundler, which finds `./db` and
+ * `./db.js` alike. A JavaScript project is also read through a tsconfig file with `allowJs`.
+ *
+ * Imports are resolved by the installed TypeScript compiler, with the options of the project
+ * that owns the file: `paths`, package `exports` and `imports`, and project references.
+ */
+export declare function loadProject(tsconfig: string | readonly string[], options?: LoadOptions): Project;
+/** Parses JSON that may have comments and trailing commas, as tsconfig files do. */
+export declare function parseJsonWithComments(text: string, file: string): unknown;