@aoelite/refpact-ts 0.0.0-stage → 0.1.2

package/dist/filters.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The filters of a rule: what it leaves out, why it exists and how much it weighs.
+ *
+ * A rule, layers and an onion architecture have the same filters. Each filter is written
+ * once, here: {@link addFilters} gives its method to all of them, so a new filter cannot be
+ * missing from one.
+ */
+import type { Rule as CoreRule } from "./core/index.ts";
+import type { Kind } from "./frontend/imports.ts";
+import type { AnyOf } from "./rules.ts";
+/** One filter, as a value that a set of rules keeps until its rules are made. @internal */
+export interface Filter {
+    /**
+     * Whether the filter says which imports a rule sees. A rule that looks at no import, such
+     * as "every file is in a layer", does not get such a filter: there, an exemption that lets
+     * nothing pass would be an error.
+     */
+    readonly aboutImports: boolean;
+    /** The rule of the core with the filter. */
+    readonly apply: (rule: CoreRule) => CoreRule;
+}
+/** What has filters: it gives itself again with one more filter. @internal */
+export interface Filtered<Self> {
+    /** @internal */
+    filtered(filter: Filter): Self;
+}
+/** The filters of a rule, of layers and of an onion architecture. */
+export interface Filters<Self> {
+    /**
+     * Says why this exists. The report of a violation prints the reason below the name of the
+     * rule, so whoever breaks the rule learns what it protects.
+     */
+    because(reason: string): Self;
+    /**
+     * Makes this a warning: the violations are reported with `console.warn`, and the check
+     * passes. A rule that cannot fail as written is still an error, and so is a stale
+     * baseline. {@link ImportRule.evaluate} gives the violations of a warning as of any rule.
+     *
+     * ```ts
+     * rule("new code does not print").files(all()).mustNotContain("console").asWarning().check(app);
+     * ```
+     */
+    asWarning(): Self;
+    /** Counts only these kinds of import. */
+    onlyKinds(...kinds: Kind[]): Self;
+    /** Counts all kinds of import except these. */
+    ignoringKinds(...kinds: Kind[]): Self;
+    /**
+     * Leaves out the imports that the analysis could not prove: the files that a computed
+     * specifier such as `` import(`./locales/${name}.ts`) `` can name.
+     */
+    ignoringCandidates(): Self;
+    /** Leaves out `import type`, type-only names, `import("m")` in types, and `export type .. from`. */
+    ignoringTypeImports(): Self;
+    /**
+     * The imports from these files of these targets are not seen: one known import that is
+     * allowed. Files match as the files of a rule do; targets as in `mustNotImport`. For a
+     * cycle or a chain, the import is no edge.
+     *
+     * An exemption that lets no import pass is an error, so it goes when the code that it
+     * allows goes. Call this again for more exemptions.
+     */
+    ignoringImport(from: AnyOf<string>, to: AnyOf): Self;
+}
+/**
+ * Gives a class the methods of {@link Filters}. The class says that it has them with
+ * `interface Name extends Filters<Name> {}`.
+ *
+ * @internal
+ */
+export declare function addFilters(target: {
+    readonly prototype: Filtered<unknown>;
+}): void;

package/dist/filters.js

@@ -0,0 +1,39 @@
+import { filePattern, targetPattern } from "./patterns.js";
+const about = (apply) => ({ aboutImports: true, apply });
+/** The methods of {@link Filters}, written once for every class that has them. */
+const methods = {
+    because(reason) {
+        return this.filtered({ aboutImports: false, apply: (rule) => ({ ...rule, reason }) });
+    },
+    asWarning() {
+        return this.filtered({ aboutImports: false, apply: (rule) => ({ ...rule, severity: "warning" }) });
+    },
+    onlyKinds(...kinds) {
+        return this.filtered(about((rule) => ({ ...rule, kinds: { type: "only", kinds } })));
+    },
+    ignoringKinds(...kinds) {
+        return this.filtered(about((rule) => ({ ...rule, kinds: { type: "except", kinds } })));
+    },
+    ignoringCandidates() {
+        return this.filtered(about((rule) => ({ ...rule, candidates: "ignore" })));
+    },
+    ignoringTypeImports() {
+        return this.filtered(about((rule) => ({ ...rule, kinds: { type: "except", kinds: ["import-type", "export-type-from"] } })));
+    },
+    ignoringImport(from, to) {
+        const exemption = { from: from.patterns.map(filePattern), to: to.patterns.map(targetPattern) };
+        return this.filtered(about((rule) => ({ ...rule, exemptions: [...(rule.exemptions ?? []), exemption] })));
+    },
+};
+/**
+ * Gives a class the methods of {@link Filters}. The class says that it has them with
+ * `interface Name extends Filters<Name> {}`.
+ *
+ * @internal
+ */
+export function addFilters(target) {
+    Object.defineProperties(target.prototype, Object.getOwnPropertyDescriptors(methods));
+    for (const name of Object.keys(methods)) {
+        Object.defineProperty(target.prototype, name, { enumerable: false });
+    }
+}

package/dist/frontend/checks.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Switches for the tests of this package. Each one makes a short way of the front end also
+ * take the long way, and a difference between the two is an error.
+ *
+ * - `aliases`: the first step of an alias is read from the exports of the module. With the
+ *   switch, it is compared with the answer of the compiler for that name.
+ * - `walk`: a node whose text has no word that can name a module is not visited. With the
+ *   switch, all nodes are also visited, and the two visits must find the same.
+ *
+ * @internal
+ */
+export declare const checks: {
+    aliases: boolean;
+    walk: boolean;
+};

package/dist/frontend/checks.js

@@ -0,0 +1,12 @@
+/**
+ * Switches for the tests of this package. Each one makes a short way of the front end also
+ * take the long way, and a difference between the two is an error.
+ *
+ * - `aliases`: the first step of an alias is read from the exports of the module. With the
+ *   switch, it is compared with the answer of the compiler for that name.
+ * - `walk`: a node whose text has no word that can name a module is not visited. With the
+ *   switch, all nodes are also visited, and the two visits must find the same.
+ *
+ * @internal
+ */
+export const checks = { aliases: false, walk: false };

package/dist/frontend/classic.d.ts

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

package/dist/frontend/classic.js

@@ -0,0 +1,105 @@
+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;
+};
+import { COMPONENT_EXTENSIONS } from "./components.js";
+/** Loads the compiler of the installed TypeScript 6. */
+export async function loadClassic(installed) {
+    const ts = (await import(__rewriteRelativeImportExtension(installed.packageName))).default;
+    return {
+        SyntaxKind: ts.SyntaxKind,
+        jsDocBesideChildren: true,
+        openProjects: (_root, configFiles, files) => ({
+            projects: configFiles.map((configFile) => open(ts, configFile, files)),
+            // The compiler is in this process, so there is nothing to stop.
+            close() { },
+        }),
+    };
+}
+/** Opens one tsconfig file as a program. */
+function open(ts, configFile, files) {
+    const system = files === undefined ? ts.sys : withComponents(ts.sys, files);
+    const parsed = ts.getParsedCommandLineOfConfigFile(configFile, undefined, {
+        ...system,
+        onUnRecoverableConfigFileDiagnostic(diagnostic) {
+            const message = ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n");
+            throw new Error(`refpact: the TypeScript compiler did not load ${configFile}: ${message}`);
+        },
+    });
+    if (parsed === undefined) {
+        throw new Error(`refpact: the TypeScript compiler did not load ${configFile}`);
+    }
+    const host = ts.createCompilerHost(parsed.options, true);
+    host.readFile = system.readFile;
+    host.fileExists = system.fileExists;
+    // An import of a referenced project leads to its source, as with TypeScript 7, and not to
+    // the declaration files of a build that may not exist.
+    host.useSourceOfProjectReferenceRedirect = () => true;
+    const program = ts.createProgram({
+        rootNames: parsed.fileNames,
+        options: parsed.options,
+        host,
+        ...(parsed.projectReferences === undefined ? {} : { projectReferences: parsed.projectReferences }),
+    });
+    const checker = program.getTypeChecker();
+    const Flags = ts.SymbolFlags;
+    const memberFlags = Flags.Property | Flags.Method | Flags.GetAccessor | Flags.SetAccessor | Flags.EnumMember;
+    const ownerFlags = Flags.Class | Flags.Interface | Flags.RegularEnum | Flags.ConstEnum;
+    const native = (symbol) => symbol;
+    return {
+        configFile,
+        options: parsed.options,
+        ownFiles: program
+            .getSourceFiles()
+            .filter((file) => !program.isSourceFileDefaultLibrary(file) && !program.isSourceFileFromExternalLibrary(file))
+            .map((file) => file.fileName),
+        sourceFile: (file) => program.getSourceFile(file),
+        // The program holds its syntax trees for as long as it lives.
+        forgetSourceFiles() { },
+        symbolsAt: (nodes) => nodes.map((node) => known(checker, checker.getSymbolAtLocation(node))),
+        shorthandValueAt: (property) => known(checker, checker.getShorthandAssignmentValueSymbol(property)),
+        filesOf: (symbol) => (native(symbol).declarations ?? []).map((declaration) => declaration.getSourceFile().fileName),
+        same: (a, b) => a === b,
+        ownerOf(symbol) {
+            if ((native(symbol).flags & memberFlags) === 0) {
+                return undefined;
+            }
+            // A member is declared inside its owner, and the name of the owner has its symbol.
+            const name = native(symbol).declarations?.[0]?.parent?.name;
+            const owner = name === undefined ? undefined : checker.getSymbolAtLocation(name);
+            return owner !== undefined && (owner.flags & ownerFlags) !== 0 ? owner : undefined;
+        },
+        isTypeParameter: (symbol) => (native(symbol).flags & Flags.TypeParameter) !== 0,
+        immediateAlias: (symbol) => (native(symbol).flags & Flags.Alias) === 0 ? undefined : known(checker, checker.getImmediateAliasedSymbol(native(symbol))),
+        exportsOf: (module) => new Map(checker.getExportsOfModule(native(module)).map((symbol) => [symbol.name, symbol])),
+    };
+}
+/** The symbol, when the compiler found what it stands for. */
+function known(checker, symbol) {
+    return symbol === undefined || checker.isUnknownSymbol(symbol) ? undefined : symbol;
+}
+/**
+ * The file system of the compiler with the component files in it. A component file
+ * `App.svelte` is there as `App.svelte.ts`, as `components.ts` describes.
+ */
+function withComponents(system, files) {
+    return {
+        ...system,
+        readFile: (fileName, encoding) => files.readFile(fileName) ?? system.readFile(fileName, encoding),
+        fileExists: (fileName) => files.fileExists(fileName) ?? system.fileExists(fileName),
+        // The files of a tsconfig. A pattern that names `.ts` files names the component files
+        // too, under the names that they are shown with.
+        readDirectory(directory, extensions, excludes, includes, depth) {
+            const found = system.readDirectory(directory, extensions, excludes, includes, depth);
+            const components = system
+                .readDirectory(directory, COMPONENT_EXTENSIONS, excludes, includes?.map((pattern) => pattern.replace(/\.ts$/, "")), depth)
+                .map((file) => `${file}.ts`)
+                .filter((file) => files.fileExists(file) === true);
+            return [...found, ...components];
+        },
+    };
+}

package/dist/frontend/compiler.d.ts

@@ -0,0 +1,93 @@
+import type { ComponentFiles } from "./components.ts";
+/** A node of a syntax tree. */
+export interface Node {
+    readonly kind: number;
+    /** Where the node begins in the text of the file, with the comments before it. */
+    readonly pos: number;
+    /** The position after the last character of the node in the text of the file. */
+    readonly end: number;
+    forEachChild(visit: (child: Node) => void): void;
+    getStart(sourceFile: SourceFile): number;
+}
+export interface SourceFile extends Node {
+    /** The text of the file. The positions of nodes count in it. */
+    readonly text: string;
+    getLineAndCharacterOfPosition(position: number): {
+        readonly line: number;
+        readonly character: number;
+    };
+}
+/** A symbol of the compiler. Only its name is read directly; the project answers the rest. */
+export interface TsSymbol {
+    readonly name: string;
+}
+/** One opened tsconfig project. */
+export interface CompilerProject {
+    readonly configFile: string;
+    readonly options: Readonly<Record<string, unknown>>;
+    /** Absolute names of the files of the program, without default libraries and external packages. */
+    readonly ownFiles: readonly string[];
+    sourceFile(file: string): SourceFile | undefined;
+    /**
+     * Lets go of the syntax trees that `sourceFile` gave, so that their memory can be used
+     * again. The trees that the caller still holds stay valid.
+     */
+    forgetSourceFiles(): void;
+    /**
+     * The symbols at many nodes: `undefined` where the compiler finds none. With the native
+     * compiler this is one round trip.
+     */
+    symbolsAt(nodes: readonly Node[]): (TsSymbol | undefined)[];
+    /** The symbol of the value of a shorthand property: `fetch` in `{ fetch }`. One round trip. */
+    shorthandValueAt(property: Node): TsSymbol | undefined;
+    /** Absolute names of the files that declare the symbol. */
+    filesOf(symbol: TsSymbol): string[];
+    /** True when the two are the same symbol. */
+    same(a: TsSymbol, b: TsSymbol): boolean;
+    /**
+     * The class, the interface or the enum that declares a member: a property, a method, an
+     * accessor or an enum member. `undefined` for other symbols, and for a member of a type
+     * without a name.
+     */
+    ownerOf(symbol: TsSymbol): TsSymbol | undefined;
+    /** True when the symbol is a type parameter, as `T` in `function first<T>(items: T[]): T`. */
+    isTypeParameter(symbol: TsSymbol): boolean;
+    /** One step from an alias to what it stands for. `undefined` when the symbol is not an alias. */
+    immediateAlias(symbol: TsSymbol): TsSymbol | undefined;
+    /**
+     * All that a module exports, also through `export *`, by name. With the native compiler
+     * this is one round trip for each module.
+     */
+    exportsOf(module: TsSymbol): ReadonlyMap<string, TsSymbol>;
+}
+export interface CompilerSession {
+    readonly projects: readonly CompilerProject[];
+    close(): void;
+}
+/** What a backend gives. */
+export interface Backend {
+    /** The numbers of the kinds of nodes. They differ between versions of the compiler. */
+    readonly SyntaxKind: Readonly<Record<string, number>>;
+    /**
+     * Where the nodes of a JSDoc comment are. `true`: in the field `jsDoc` of the node after
+     * the comment, as in TypeScript 6. `false`: among the children, as in TypeScript 7.
+     */
+    readonly jsDocBesideChildren: boolean;
+    openProjects(root: string, configFiles: readonly string[], files?: ComponentFiles): CompilerSession;
+}
+/** The installed `typescript` package. */
+export interface Installed {
+    readonly packageName: string;
+    readonly version: string;
+    readonly exports: Readonly<Record<string, unknown>>;
+}
+/** The version of the compiler that reads the projects, such as `7.0.2`. */
+export declare const compilerVersion: string;
+declare const KIND_NAMES: readonly ["CallExpression", "CatchClause", "AsExpression", "BinaryExpression", "ConditionalExpression", "NewExpression", "NonNullExpression", "ParenthesizedExpression", "PlusToken", "SatisfiesExpression", "TemplateExpression", "ArrayLiteralExpression", "AbstractKeyword", "ArrayBindingPattern", "ArrowFunction", "AsyncKeyword", "Block", "BindingElement", "ClassDeclaration", "ConstKeyword", "Constructor", "DebuggerStatement", "DeclareKeyword", "Decorator", "DefaultKeyword", "EnumMember", "EnumDeclaration", "ExportKeyword", "ExtendsKeyword", "ForInStatement", "ForOfStatement", "ForStatement", "FunctionDeclaration", "FunctionExpression", "GetAccessor", "HeritageClause", "ImplementsKeyword", "InterfaceDeclaration", "ModuleDeclaration", "TypeAliasDeclaration", "VariableStatement", "ExportDeclaration", "ExternalModuleReference", "Identifier", "ImportClause", "ImportDeclaration", "ImportEqualsDeclaration", "ImportKeyword", "ImportSpecifier", "ImportType", "MethodDeclaration", "JsxAttribute", "JsxClosingElement", "JsxOpeningElement", "JsxSelfClosingElement", "MetaProperty", "NamedExports", "NamedImports", "NamespaceImport", "NoSubstitutionTemplateLiteral", "ObjectBindingPattern", "Parameter", "PropertyAssignment", "PropertyDeclaration", "PropertySignature", "PropertyAccessExpression", "QualifiedName", "SetAccessor", "ShorthandPropertyAssignment", "StringLiteral", "TypeKeyword", "TypeQuery", "TypeReference", "VariableDeclaration", "VariableDeclarationList"];
+/** See {@link Backend.jsDocBesideChildren}. */
+export declare const jsDocBesideChildren: boolean;
+export type SyntaxKind = number;
+export declare const SyntaxKind: Readonly<Record<(typeof KIND_NAMES)[number], number>>;
+/** Opens the given tsconfig files with the installed compiler. */
+export declare function openProjects(root: string, configFiles: readonly string[], files?: ComponentFiles): CompilerSession;
+export {};

package/dist/frontend/compiler.js

@@ -0,0 +1,116 @@
+/**
+ * What the front end needs from a TypeScript compiler.
+ *
+ * The installed `typescript` package is the compiler, so a project is read by the same
+ * compiler that builds it. `native.ts` talks to the native compiler of TypeScript 7 through
+ * the client that the package ships. `classic.ts` runs the compiler of TypeScript 6 in this
+ * process.
+ */
+import { createRequire } from "node:module";
+import { loadClassic } from "./classic.js";
+import { loadNative } from "./native.js";
+// REFPACT_TYPESCRIPT names the package to load instead of `typescript`. It is a switch for
+// tests and development only, to run the tests against a second compiler that is installed
+// under an alias, for example `REFPACT_TYPESCRIPT=typescript-6`.
+const packageName = process.env["REFPACT_TYPESCRIPT"] || "typescript";
+const manifest = createRequire(import.meta.url)(`${packageName}/package.json`);
+const installed = { packageName, version: manifest.version, exports: manifest.exports ?? {} };
+/** The version of the compiler that reads the projects, such as `7.0.2`. */
+export const compilerVersion = installed.version;
+const major = Number(installed.version.split(".")[0]);
+if (major !== 6 && major !== 7) {
+    throw new Error(`refpact: TypeScript ${installed.version} is not supported. Install TypeScript 6 or 7.`);
+}
+const backend = major === 6 ? await loadClassic(installed) : await loadNative(installed);
+// The kinds that the front end reads. A compiler that does not have one of them is not one
+// that this code was written for, so that is an error here and not a silent miss later.
+const KIND_NAMES = [
+    "CallExpression",
+    "CatchClause",
+    "AsExpression",
+    "BinaryExpression",
+    "ConditionalExpression",
+    "NewExpression",
+    "NonNullExpression",
+    "ParenthesizedExpression",
+    "PlusToken",
+    "SatisfiesExpression",
+    "TemplateExpression",
+    "ArrayLiteralExpression",
+    "AbstractKeyword",
+    "ArrayBindingPattern",
+    "ArrowFunction",
+    "AsyncKeyword",
+    "Block",
+    "BindingElement",
+    "ClassDeclaration",
+    "ConstKeyword",
+    "Constructor",
+    "DebuggerStatement",
+    "DeclareKeyword",
+    "Decorator",
+    "DefaultKeyword",
+    "EnumMember",
+    "EnumDeclaration",
+    "ExportKeyword",
+    "ExtendsKeyword",
+    "ForInStatement",
+    "ForOfStatement",
+    "ForStatement",
+    "FunctionDeclaration",
+    "FunctionExpression",
+    "GetAccessor",
+    "HeritageClause",
+    "ImplementsKeyword",
+    "InterfaceDeclaration",
+    "ModuleDeclaration",
+    "TypeAliasDeclaration",
+    "VariableStatement",
+    "ExportDeclaration",
+    "ExternalModuleReference",
+    "Identifier",
+    "ImportClause",
+    "ImportDeclaration",
+    "ImportEqualsDeclaration",
+    "ImportKeyword",
+    "ImportSpecifier",
+    "ImportType",
+    "MethodDeclaration",
+    "JsxAttribute",
+    "JsxClosingElement",
+    "JsxOpeningElement",
+    "JsxSelfClosingElement",
+    "MetaProperty",
+    "NamedExports",
+    "NamedImports",
+    "NamespaceImport",
+    "NoSubstitutionTemplateLiteral",
+    "ObjectBindingPattern",
+    "Parameter",
+    "PropertyAssignment",
+    "PropertyDeclaration",
+    "PropertySignature",
+    "PropertyAccessExpression",
+    "QualifiedName",
+    "SetAccessor",
+    "ShorthandPropertyAssignment",
+    "StringLiteral",
+    "TypeKeyword",
+    "TypeQuery",
+    "TypeReference",
+    "VariableDeclaration",
+    "VariableDeclarationList",
+];
+/** See {@link Backend.jsDocBesideChildren}. */
+export const jsDocBesideChildren = backend.jsDocBesideChildren;
+export const SyntaxKind = Object.fromEntries(KIND_NAMES.map((name) => {
+    const value = backend.SyntaxKind[name];
+    if (typeof value !== "number") {
+        throw new Error(`refpact: TypeScript ${installed.version} has no SyntaxKind.${name}`);
+    }
+    return [name, value];
+}));
+/** Opens the given tsconfig files with the installed compiler. */
+export function openProjects(root, configFiles, files) {
+    return backend.openProjects(root, configFiles, files);
+}

package/dist/frontend/components.d.ts

@@ -0,0 +1,29 @@
+/** The extensions of the component files that are read. */
+export declare const COMPONENT_EXTENSIONS: readonly ComponentExtension[];
+/** The extension of a kind of component file that refpact reads. */
+export type ComponentExtension = ".svelte" | ".vue" | ".astro";
+/** What the compiler asks of the file system. `undefined` lets the compiler read the disk. */
+export interface ComponentFiles {
+    readFile(fileName: string): string | undefined;
+    fileExists(fileName: string): boolean | undefined;
+    getAccessibleEntries(directoryName: string): {
+        files: string[];
+        directories: string[];
+    } | undefined;
+}
+/**
+ * The text of a component file with a space in place of each character that is not code: all
+ * that is outside its `<script>` blocks, and outside the part between `---` lines at the
+ * start of an Astro file. Line breaks stay.
+ */
+export declare function scriptsOf(text: string, extension: ComponentExtension): string;
+/** The component file that a file name of the compiler stands for: `App.svelte` for `App.svelte.ts`. */
+export declare function componentOf(fileName: string, extensions: readonly ComponentExtension[]): {
+    readonly file: string;
+    readonly extension: ComponentExtension;
+} | undefined;
+/**
+ * The file system that shows the component files to the compiler. A file that is on the
+ * disk under the name, such as a module `state.svelte.ts` of Svelte, is read from the disk.
+ */
+export declare function componentFiles(extensions: readonly ComponentExtension[]): ComponentFiles;

package/dist/frontend/components.js

@@ -0,0 +1,111 @@
+/**
+ * Component files, such as `App.svelte` and `App.vue`: a file of markup that holds its code
+ * in `<script>` blocks.
+ *
+ * The compiler reads TypeScript only. So each component file is shown to it as a file with
+ * `.ts` after its name, `App.svelte.ts`, whose text is that of the component with a space in
+ * place of each character outside the scripts. The code is then at the line and the column
+ * that it has in the component, and an import of `./App.svelte` leads to the file.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+/** The extensions of the component files that are read. */
+export const COMPONENT_EXTENSIONS = [".svelte", ".vue", ".astro"];
+/** The types of the scripts that are code of the component. Other scripts, such as JSON, are data. */
+const CODE_TYPES = new Set(["", "module", "text/javascript", "text/typescript", "ts", "js", "typescript", "javascript"]);
+/**
+ * The text of a component file with a space in place of each character that is not code: all
+ * that is outside its `<script>` blocks, and outside the part between `---` lines at the
+ * start of an Astro file. Line breaks stay.
+ */
+export function scriptsOf(text, extension) {
+    const keep = [];
+    if (extension === ".astro") {
+        const front = /^\s*---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+        if (front !== null) {
+            const start = front.index + front[0].indexOf(front[1], front[0].indexOf("---") + 3);
+            keep.push([start, start + front[1].length]);
+        }
+    }
+    const block = /<script\b([^>]*)>([\s\S]*?)<\/script\s*>/gi;
+    for (let found = block.exec(text); found !== null; found = block.exec(text)) {
+        const attributes = found[1];
+        const type = /\btype\s*=\s*["']?([^"'\s>]*)/i.exec(attributes)?.[1] ?? "";
+        if (/\bsrc\s*=/i.test(attributes) || !CODE_TYPES.has(type.toLowerCase())) {
+            continue;
+        }
+        const start = found.index + found[0].indexOf(">") + 1;
+        keep.push([start, start + found[2].length]);
+    }
+    let code = "";
+    let at = 0;
+    for (const [start, end] of keep.sort((a, b) => a[0] - b[0])) {
+        if (start < at) {
+            continue;
+        }
+        code += text.slice(at, start).replace(/[^\r\n]/g, " ") + text.slice(start, end);
+        at = end;
+    }
+    return code + text.slice(at).replace(/[^\r\n]/g, " ");
+}
+/** The component file that a file name of the compiler stands for: `App.svelte` for `App.svelte.ts`. */
+export function componentOf(fileName, extensions) {
+    if (!fileName.endsWith(".ts")) {
+        return undefined;
+    }
+    const file = fileName.slice(0, -".ts".length);
+    const extension = extensions.find((known) => file.endsWith(known));
+    return extension === undefined ? undefined : { file, extension };
+}
+/**
+ * The file system that shows the component files to the compiler. A file that is on the
+ * disk under the name, such as a module `state.svelte.ts` of Svelte, is read from the disk.
+ */
+export function componentFiles(extensions) {
+    const isFile = (file) => {
+        try {
+            return statSync(file).isFile();
+        }
+        catch {
+            return false;
+        }
+    };
+    const shown = (fileName) => {
+        const component = componentOf(fileName, extensions);
+        return component !== undefined && !existsSync(fileName) && isFile(component.file) ? component : undefined;
+    };
+    return {
+        readFile(fileName) {
+            const component = shown(fileName);
+            return component === undefined ? undefined : scriptsOf(readFileSync(component.file, "utf8"), component.extension);
+        },
+        fileExists: (fileName) => (shown(fileName) !== undefined ? true : undefined),
+        getAccessibleEntries(directoryName) {
+            let names;
+            try {
+                names = readdirSync(directoryName);
+            }
+            catch {
+                return undefined;
+            }
+            if (!names.some((name) => extensions.some((extension) => name.endsWith(extension)))) {
+                return undefined;
+            }
+            const files = [];
+            const directories = [];
+            for (const name of names) {
+                const entry = path.join(directoryName, name);
+                if (isFile(entry)) {
+                    files.push(name);
+                    if (extensions.some((extension) => name.endsWith(extension)) && !names.includes(`${name}.ts`)) {
+                        files.push(`${name}.ts`);
+                    }
+                }
+                else if (existsSync(entry)) {
+                    directories.push(name);
+                }
+            }
+            return { files, directories };
+        },
+    };
+}

package/dist/frontend/declarations.d.ts

@@ -0,0 +1,45 @@
+import type { Node, SourceFile } from "./compiler.ts";
+/** A kind of item: `function`, `class`, `interface`, `type`, `enum`, `variable` or `namespace`. */
+export type ItemKind = "function" | "class" | "interface" | "type" | "enum" | "variable" | "namespace" | "package";
+/** The kinds of item a declaration can have. */
+export declare const ITEM_KINDS: readonly ItemKind[];
+/** `exported`: the module exports the item, also under another name. `local`: it does not. */
+export type Visibility = "exported" | "local";
+/** The visibilities a declaration can have. */
+export declare const VISIBILITIES: readonly Visibility[];
+/**
+ * The relations that the syntax of a declaration gives: `extends` and `implements` of a class
+ * or an interface, the decorators of a class, and the types that a function takes and
+ * returns and that a variable has.
+ */
+export declare const TIES: readonly ["extends", "implements", "decorator", "returns", "takes", "has-type"];
+/**
+ * What a declaration says of its item besides its kind and its visibility: `async`,
+ * `abstract`, `declare`, `const` (a `const` variable or a `const enum`), `default` (an
+ * `export default` function or class), and `documented` (a JSDoc comment before it).
+ */
+export type Modifier = "async" | "abstract" | "declare" | "const" | "default" | "documented";
+/** The modifiers a declaration can have, in the order of their description. */
+export declare const MODIFIERS: readonly Modifier[];
+/** All relations of a declaration: the ties, and the types that it extends or implements at any depth. */
+export declare const RELATIONS: readonly ["extends", "implements", "decorator", "returns", "takes", "has-type", "assignable-to"];
+/** One tie of a declaration, by the node that names its target. */
+export interface Tie {
+    readonly relation: (typeof TIES)[number];
+    readonly node: Node;
+}
+/** A top-level declaration of a file, before its names are resolved. */
+export interface Declared {
+    readonly name: string;
+    readonly kind: ItemKind;
+    /** The node of the name, or of the declaration when it has no name. */
+    readonly at: Node;
+    /** The node of the whole declaration: the item ends where it ends. */
+    readonly whole: Node;
+    /** True when the declaration has the `export` modifier. */
+    readonly exported: boolean;
+    readonly ties: readonly Tie[];
+    readonly modifiers: readonly Modifier[];
+}
+/** The top-level declarations of a file, in the order of the text. */
+export declare function collectDeclarations(sourceFile: SourceFile): Declared[];