@codependix/file-imports 0.0.0-stage → 0.0.4

package/dist/src/index.d.ts

@@ -0,0 +1,504 @@
+import { default as default_2 } from 'typescript';
+
+/** Header declaring the mermaid diagram type and its default layout direction. */
+export declare const FILE_IMPORTS_WORKSPACE_GRAPH_MERMAID_HEADER = "graph LR";
+
+/** Rendered in place of a diagram for a workspace with no internal file imports at all. */
+export declare const FILE_IMPORTS_WORKSPACE_GRAPH_UNCONNECTED = "_This workspace has no internal file imports, in any project._";
+
+/**
+ * The whole-workspace file-level import graph: every TypeScript and Python
+ * project's own internal import graph, combined into one.
+ *
+ * Exported once at the workspace root rather than once per project — see
+ * `codependix-nx-projects`'s `WorkspaceGraph`, which this mirrors. A file name
+ * alone is not unique across the workspace the way a project name is, so
+ * every node here is qualified with the project it belongs to (see
+ * `WorkspaceGraphService.qualifyFileName`) rather than reused as-is from a
+ * single project's `TypescriptImportGraph`/`PythonImportGraph`.
+ */
+export declare interface FileImportsWorkspaceGraph {
+    /** Every drawn import relationship, sorted so the diagram never churns. */
+    readonly edges: FileImportsWorkspaceGraphEdge[];
+    /** Every file in the graph, qualified by project and sorted. */
+    readonly fileNames: string[];
+}
+
+/** One file importing another, both qualified by the project they belong to. */
+export declare interface FileImportsWorkspaceGraphEdge {
+    readonly source: string;
+    readonly target: string;
+}
+
+/** Provides the whole-workspace file-level import graph builder. */
+export declare class FileImportsWorkspaceGraphModule {
+}
+
+/**
+ * Builds the whole-workspace file-level import graph — every TypeScript and
+ * Python project's own internal import graph, combined into one — exported
+ * once at the workspace root rather than once per project.
+ *
+ * Combines both languages into one graph rather than two, matching how
+ * `fileImports` reads as one merged concept everywhere else in codependix:
+ * `boundaries.fileImports` is the only place the two still separate, because
+ * a Python file can never import a TypeScript file or vice versa and the rule
+ * vocabularies differ — nothing like that applies to simply drawing both
+ * languages' already-built graphs on one page.
+ *
+ * A file name alone is only unique within its own project, unlike an Nx
+ * project name, which is unique workspace-wide — so every node is qualified
+ * with the project it belongs to before the two languages' graphs are
+ * combined, mirroring `codependix-nx-projects`'s `WorkspaceGraphService`
+ * without reusing its code, since the two build genuinely different kinds of
+ * graph from genuinely different sources.
+ */
+export declare class FileImportsWorkspaceGraphService {
+    constructor();
+    /** Sorts edges by source then target so a rendered diagram never churns. */
+    private compareEdges;
+    /** Qualifies a project-relative file name with the project it belongs to. */
+    private qualifyFileName;
+    /** Renders one qualified file name as a mermaid node. */
+    private renderNode;
+    /** Sorts names into a stable order. */
+    private sortNames;
+    /** Turns a qualified file name into an identifier mermaid accepts. */
+    private toNodeIdentifier;
+    /**
+     * Builds the whole-workspace file-level import graph from every discovered
+     * TypeScript and Python project's own already-built import graph.
+     */
+    buildWorkspaceGraph(args: {
+        pythonGraphs: PythonImportGraph[];
+        typescriptGraphs: TypescriptImportGraph[];
+    }): FileImportsWorkspaceGraph;
+    /** Renders the whole-workspace file-level import graph as a mermaid diagram. */
+    renderMermaid(workspaceGraph: FileImportsWorkspaceGraph): string;
+}
+
+/**
+ * A Python project's internal file-level import Graph: which of its own
+ * files import which other of its own files.
+ *
+ * Shaped identically to the `typescript` module's `TypescriptImportGraph`,
+ * kept as its own type rather than shared: the two modules build the same
+ * kind of graph from entirely different sources — a `ts.Program` versus a
+ * hand-rolled statement parser — the same independence `codependix-nx-projects` and
+ * `codependix-nestjs-modules` already keep from each other and from
+ * `codependix-file-imports`.
+ */
+export declare interface PythonImportGraph {
+    /** Every drawn import relationship, sorted so the diagram never churns. */
+    readonly edges: PythonImportGraphEdge[];
+    /** Every source file in the graph, project-relative and sorted. */
+    readonly fileNames: string[];
+    /** Files left with no drawn edge in either direction. */
+    readonly isolatedFileNames: string[];
+    /** The project the graph was built from. */
+    readonly projectName: string;
+}
+
+/** One file importing another, both paths project-relative. */
+export declare interface PythonImportGraphEdge {
+    readonly source: string;
+    readonly target: string;
+}
+
+/**
+ * Builds a Python project's internal file-level import Graph, and renders it.
+ *
+ * Every source file's top-level import statements are read through
+ * `PythonImportParserService`, then each specifier is resolved to a real
+ * file with `resolveSpecifierPath` — the closest Python equivalent of
+ * `ts.resolveModuleName`, since Python has no compiler API to delegate to.
+ * An absolute specifier (`from src.grammars import Grammar`) resolves
+ * relative to the project root; a relative one (`from .grammars import Grammar`)
+ * resolves relative to the importing file's own directory, ascended once per
+ * extra leading dot. An edge is kept only when it resolves to a file this
+ * project owns, the same rule `TypescriptImportGraphService.buildGraph` applies.
+ */
+export declare class PythonImportGraphService {
+    private readonly pythonImportParserService;
+    private readonly pythonProjectService;
+    constructor(pythonImportParserService: PythonImportParserService, pythonProjectService: PythonProjectService);
+    /** Walks a directory upward a number of levels. */
+    private ascendDirectories;
+    /** Collects every internal import edge one source file declares. */
+    private collectEdgesForFile;
+    /** Sorts edges by source then target so a rendered diagram never churns. */
+    private compareEdges;
+    /** Drops duplicate edges, keeping the sorted order they were built in. */
+    private dedupeEdges;
+    /** Renders one file as a mermaid node, labelled with its relative path. */
+    private renderNode;
+    /**
+     * Resolves an import specifier to an absolute file path, checked against
+     * the filesystem — the closest Python has to `ts.resolveModuleName`
+     * checking against a compiler host.
+     *
+     * A specifier with no module path (`from . import name`) resolves the
+     * package directory itself — its `__init__.py` — since there is no
+     * standalone file a bare relative import could otherwise name.
+     */
+    private resolveSpecifierPath;
+    /** Turns a relative file path into an identifier mermaid accepts. */
+    private toNodeIdentifier;
+    /** Expresses an absolute file path relative to its project, POSIX-style. */
+    private toRelativePath;
+    /** Builds a Python project's internal file-level import Graph. */
+    buildGraph(project: PythonProject): PythonImportGraph;
+    /** Renders an import graph as a fenced mermaid diagram. */
+    renderMermaid(graph: PythonImportGraph): string;
+}
+
+/**
+ * Parses a Python source file's top-level `import`/`from ... import`
+ * statements into the module each one names.
+ *
+ * There is no `ast`-equivalent compiler API available from Node the way
+ * `ts.isImportDeclaration` walks a real `ts.Program`, so statements are
+ * recognized with a small hand-rolled scanner instead: comments and quoted
+ * strings are stripped so a `#` or a quote character inside either never
+ * confuses the parser, a statement's continuation lines are rejoined by
+ * tracking parenthesis depth and trailing backslashes, and only statements
+ * starting at column zero are considered — an import nested inside a
+ * function or a conditional is deliberately not walked, the same way a
+ * TypeScript `import` declaration can only ever appear at module scope.
+ */
+export declare class PythonImportParserService {
+    constructor();
+    /**
+     * Rejoins a statement's continuation lines starting at `startIndex` into
+     * one line, tracking parenthesis depth and trailing backslashes.
+     */
+    private collectStatement;
+    /** Counts how many times a single character appears in a line. */
+    private countCharacter;
+    /** Whether a raw line starts a module-level `import`/`from` statement. */
+    private isTopLevelImportStart;
+    /** Counts a raw line's leading whitespace. */
+    private measureIndent;
+    /** Parses a joined `from <dots><module> import ...` statement. */
+    private parseFromStatement;
+    /** Parses a joined `import <specifiers>` statement. */
+    private parseImportStatement;
+    /** Parses one joined statement into the module(s) it names. */
+    private parseStatement;
+    /** Strips a trailing `#` comment, ignoring one found inside a quoted string. */
+    private stripComment;
+    /** Parses every module-level import statement in a Python source file. */
+    parseImportSpecifiers(source: string): PythonImportSpecifier[];
+}
+
+/**
+ * One module a Python `import`/`from ... import` statement names.
+ *
+ * Only the module being imported from is kept — which names a `from`
+ * statement pulls out of it is irrelevant to a file-level import graph, the
+ * same way `codependix-file-imports` resolves only a TypeScript import
+ * declaration's `moduleSpecifier` and never looks at what it binds.
+ */
+declare interface PythonImportSpecifier {
+    /**
+     * How many leading dots a `from` statement's module carried.
+     *
+     * `0` for an absolute import (`import`, or `from x import y`); `1` for
+     * `from . import y` or `from .x import y`; `2` for `from .. import y`;
+     * and so on.
+     */
+    readonly level: number;
+    /**
+     * The dotted module path, with dots left in (`"src.grammars"`), or an
+     * empty string for a bare relative import (`from . import y`).
+     */
+    readonly modulePath: string;
+}
+
+/**
+ * Provides the `python` module's public surface, `PythonService`.
+ *
+ * `PythonProjectService`, `PythonImportParserService`, and
+ * `PythonImportGraphService` stay internal collaborators — not exported —
+ * so a consumer of this package reaches every Python capability through one
+ * facade.
+ */
+export declare class PythonModule {
+}
+
+/**
+ * A workspace project tagged `language:python`, discovered from the Nx
+ * project graph the same way `codependix-nestjs-modules`'s `NestjsProject` is —
+ * Python has no per-project marker file as reliable as a NestJS project's
+ * root module, since every Python project shares one workspace-root
+ * `pyproject.toml` (see the `write-python` skill) even when it also carries
+ * its own.
+ */
+export declare interface PythonProject {
+    /** Absolute path of the project directory. */
+    readonly absoluteRoot: string;
+    /** Project directory name, which is also the Nx project name. */
+    readonly name: string;
+}
+
+/**
+ * Discovers the workspace's Python projects and lists each one's source
+ * files.
+ *
+ * Discovery reads each project's own `language:python` tag, the same
+ * way `codependix-nestjs-modules`'s `NestjsProjectService` reads `framework:nestjs` —
+ * rather than probing for a marker file, since a Python project's own
+ * `pyproject.toml` is optional (every project is already a member of the
+ * workspace root's, per the `write-python` skill).
+ */
+export declare class PythonProjectService {
+    constructor();
+    /** Recursively lists every `.py` file beneath a directory, depth first. */
+    private listSourceFilesInDirectory;
+    /** Describes a project by its directory and Nx project name. */
+    describeProject(absoluteRoot: string, name: string): PythonProject;
+    /**
+     * Filters an already-read list of Nx projects down to the ones tagged
+     * `language:python`, and describes each one.
+     *
+     * Projects are returned in the order they were given, which callers keep
+     * sorted by name — the same order `TypescriptProjectService.discoverProjects`
+     * preserves.
+     */
+    discoverProjects(projects: {
+        absoluteRoot: string;
+        name: string;
+        tags: string[];
+    }[]): PythonProject[];
+    /** Reports whether a project's Nx tags mark it as a Python project. */
+    isPythonProject(project: {
+        tags: string[];
+    }): boolean;
+    /** Lists a project's own source files, absolute and sorted. */
+    listSourceFileNames(project: PythonProject): string[];
+}
+
+/**
+ * The `python` module's public surface: discovers the workspace's Python
+ * projects, and builds and renders one project's file-level import Graph.
+ *
+ * A thin facade over `PythonProjectService` (project discovery and
+ * source-file listing) and `PythonImportGraphService` (parsing those files'
+ * imports into a graph, itself backed by `PythonImportParserService`) —
+ * kept as separate collaborators internally so each stays focused, with
+ * this class the one file this repository's conformetry template for a
+ * NestJS service module expects a flat module to expose.
+ */
+export declare class PythonService {
+    private readonly pythonImportGraphService;
+    private readonly pythonProjectService;
+    constructor(pythonImportGraphService: PythonImportGraphService, pythonProjectService: PythonProjectService);
+    /** Builds a Python project's internal file-level import Graph. */
+    buildGraph(project: PythonProject): PythonImportGraph;
+    /**
+     * Filters an already-read list of Nx projects down to the ones tagged
+     * `language:python`, and describes each one.
+     */
+    discoverProjects(projects: {
+        absoluteRoot: string;
+        name: string;
+        tags: string[];
+    }[]): PythonProject[];
+    /** Renders an import graph as a fenced mermaid diagram. */
+    renderMermaid(graph: PythonImportGraph): string;
+}
+
+/**
+ * A TypeScript project's internal file-level import Graph: which of its own
+ * files import which other of its own files.
+ *
+ * Only edges resolving to a file inside the project are kept — an import of
+ * an external package or of another workspace project resolves outside
+ * `fileNames` and is left out, the same way `Neighborhood` only draws edges
+ * between projects it already knows about.
+ */
+export declare interface TypescriptImportGraph {
+    /** Every drawn import relationship, sorted so the diagram never churns. */
+    readonly edges: TypescriptImportGraphEdge[];
+    /** Every source file in the graph, project-relative and sorted. */
+    readonly fileNames: string[];
+    /** Files left with no drawn edge in either direction. */
+    readonly isolatedFileNames: string[];
+    /** The project the graph was built from. */
+    readonly projectName: string;
+}
+
+/** One file importing another, both paths project-relative. */
+export declare interface TypescriptImportGraphEdge {
+    readonly source: string;
+    readonly target: string;
+}
+
+/**
+ * Builds a project's internal file-level import Graph from a `ts.Program`,
+ * and renders it.
+ *
+ * Every import specifier is resolved through `ts.resolveModuleName`, called
+ * with the exact compiler options and host `TypescriptProjectService` built
+ * the program with — the compiler's own module resolution, so this
+ * workspace's TypeScript path aliases and NodeNext `.js`-extension imports
+ * resolve to the real `.ts` source file they point at, rather than through a
+ * hand-written path heuristic. Import declarations are detected the same way
+ * `codometer-cli`'s `TypescriptService.handleImport` does: `ts.isImportDeclaration`
+ * on a string-literal module specifier.
+ */
+export declare class TypescriptImportGraphService {
+    private readonly typescriptProjectService;
+    constructor(typescriptProjectService: TypescriptProjectService);
+    /** Collects every internal import edge one source file declares. */
+    private collectEdgesForFile;
+    /** Sorts edges by source then target so a rendered diagram never churns. */
+    private compareEdges;
+    /** Drops duplicate edges, keeping the sorted order they were built in. */
+    private dedupeEdges;
+    /**
+     * Lists a program's own source files, excluding declaration files.
+     *
+     * `program.getRootFileNames()` is the same file list
+     * `TypescriptProjectService.buildProgram` handed to `ts.createProgram` —
+     * the project's own files, not the ones it merely pulls in as
+     * dependencies.
+     */
+    private listOwnedSourceFileNames;
+    /** Renders one file as a mermaid node, labelled with its relative path. */
+    private renderNode;
+    /** Resolves an import specifier to a real, absolute file path. */
+    private resolveImportTarget;
+    /** Resolves the real, absolute file names a program owns. */
+    private resolveOwnedFileNames;
+    /** Turns a relative file path into an identifier mermaid accepts. */
+    private toNodeIdentifier;
+    /** Expresses an absolute file path relative to its project, POSIX-style. */
+    private toRelativePath;
+    /** Builds a project's internal file-level import Graph from its program. */
+    buildGraph(projectProgram: TypescriptProjectProgram): TypescriptImportGraph;
+    /** Renders an import graph as a fenced mermaid diagram. */
+    renderMermaid(graph: TypescriptImportGraph): string;
+}
+
+/**
+ * Provides the `typescript` module's public surface, `TypescriptService`.
+ *
+ * `TypescriptProjectService` and `TypescriptImportGraphService` stay
+ * internal collaborators — not exported — so a consumer of this package
+ * reaches every TypeScript capability through one facade.
+ */
+export declare class TypescriptModule {
+}
+
+/**
+ * A workspace project whose own `tsconfig.json` can be turned into a program.
+ *
+ * Every workspace project is a candidate, unlike `codependix-nestjs-modules`'s
+ * `NestjsProject`, which is gated to projects tagged `framework:nestjs` — a
+ * file-level import graph is meaningful for any TypeScript project.
+ */
+export declare interface TypescriptProject {
+    /** Absolute path of the project directory. */
+    readonly absoluteRoot: string;
+    /** Project directory name, which is also the Nx project name. */
+    readonly name: string;
+    /** Absolute path of the project's `tsconfig.json`. */
+    readonly tsconfigPath: string;
+}
+
+/**
+ * One project's program together with the compiler host and options that
+ * built it.
+ *
+ * The host and options travel with the program rather than being rebuilt by
+ * `TypescriptImportGraphService`: resolving an import specifier through
+ * `ts.resolveModuleName` needs the exact same host and options the program
+ * itself was built with, or module resolution could silently disagree with
+ * what the program actually parsed.
+ */
+export declare interface TypescriptProjectProgram {
+    readonly host: default_2.CompilerHost;
+    readonly options: default_2.CompilerOptions;
+    readonly program: default_2.Program;
+    readonly project: TypescriptProject;
+}
+
+/**
+ * Discovers the workspace's TypeScript projects and builds a `ts.Program`
+ * for each one.
+ *
+ * Every project carrying its own `tsconfig.json` is a candidate — unlike
+ * `codependix-nestjs-modules`'s `NestjsProjectService`, discovery reads no Nx tag,
+ * since a file-level import graph is meaningful for any TypeScript project.
+ * `ts.createProgram` is built the same way `callidescope-cli`'s
+ * `ProgramService` builds one: reading and fully resolving the project's own
+ * `tsconfig.json` through `ts.parseJsonSourceFileConfigFileContent`, so the
+ * program's module resolution — and therefore
+ * `TypescriptImportGraphService`'s — agrees with what `tsc` itself would resolve for
+ * this workspace's path aliases and NodeNext `.js`-extension imports.
+ */
+export declare class TypescriptProjectService {
+    constructor();
+    /**
+     * Reads and fully resolves one project's compiler options.
+     *
+     * The configuration file name is passed as the fifth argument so that
+     * TypeScript follows the `extends` chain to the shared base config and
+     * reports diagnostics against the right file, mirroring
+     * `callidescope-cli`'s `ProgramService.parseConfiguration`.
+     */
+    private parseConfiguration;
+    /** Builds one project's program, keeping the host and options alongside it. */
+    buildProgram(project: TypescriptProject): TypescriptProjectProgram;
+    /** Describes a project by its directory and Nx project name. */
+    describeProject(absoluteRoot: string, name: string): TypescriptProject;
+    /**
+     * Filters an already-read list of Nx projects down to the ones carrying
+     * their own `tsconfig.json`, and describes each one.
+     *
+     * Projects are returned in the order they were given, which callers keep
+     * sorted by name — the same order `codependix-nx-projects`'s `NeighborhoodService`
+     * reads the Nx project graph's own projects in.
+     */
+    discoverProjects(projects: {
+        absoluteRoot: string;
+        name: string;
+    }[]): TypescriptProject[];
+    /** Resolves a path through symlinks, which is how pnpm workspaces link. */
+    toRealPath(filePath: string): string;
+}
+
+/**
+ * The `typescript` module's public surface: discovers the workspace's
+ * TypeScript projects, builds each one's `ts.Program`, and builds and
+ * renders its file-level import Graph.
+ *
+ * A thin facade over `TypescriptProjectService` (project discovery and
+ * `ts.Program` construction) and `TypescriptImportGraphService` (walking
+ * that program into a graph) — kept as two separate collaborators
+ * internally so each stays focused, with this class the one file this
+ * repository's conformetry template for a NestJS service module expects a
+ * flat module to expose.
+ */
+export declare class TypescriptService {
+    private readonly typescriptImportGraphService;
+    private readonly typescriptProjectService;
+    constructor(typescriptImportGraphService: TypescriptImportGraphService, typescriptProjectService: TypescriptProjectService);
+    /** Builds a project's internal file-level import Graph from its program. */
+    buildGraph(projectProgram: TypescriptProjectProgram): TypescriptImportGraph;
+    /** Builds one project's program, keeping the host and options alongside it. */
+    buildProgram(project: TypescriptProject): TypescriptProjectProgram;
+    /**
+     * Filters an already-read list of Nx projects down to the ones carrying
+     * their own `tsconfig.json`, and describes each one.
+     */
+    discoverProjects(projects: {
+        absoluteRoot: string;
+        name: string;
+    }[]): TypescriptProject[];
+    /** Renders an import graph as a fenced mermaid diagram. */
+    renderMermaid(graph: TypescriptImportGraph): string;
+}
+
+export { }