@g3nomaly/analyze 0.0.0-stage → 0.1.1

package/dist/scanner/skills/classify.d.ts

@@ -0,0 +1,21 @@
+import type { FileKind } from '../../model';
+/** What a file inside a skill directory can be. `source` is code, shown with its symbols. */
+export type SkillFileKind = Exclude<FileKind, 'skill' | 'document'> | 'source';
+/**
+ * @brief Classifies a file in a skill by where it is and what it is. The first rule that matches wins.
+ *
+ * | Rule | Kind |
+ * |---|---|
+ * | in a `hooks/` directory | `hook` |
+ * | in an `agents/` directory | `agent` |
+ * | in a `schemas/` directory, or named like a schema | `schema` |
+ * | source code | `source` |
+ * | markdown | `reference` |
+ * | JSON | `json` |
+ * | anything else | `asset` |
+ *
+ * @param path - Path relative to the skill directory.
+ * @param isSource - Answers whether a file is source code.
+ * @returns The kind of the file, from the first rule that matches it.
+ */
+export declare function classifySkillFile(path: string, isSource: (path: string) => boolean): SkillFileKind;

package/dist/scanner/skills/layout.d.ts

@@ -0,0 +1,46 @@
+/** File name that makes a directory a skill. */
+export declare const SKILL_FILE = "SKILL.md";
+/**
+ * A skill directory and the files that belong to it.
+ *
+ * @property directory - Root-relative directory of the `SKILL.md`. `''` for the root itself.
+ * @property skillFile - Root-relative path of the `SKILL.md`.
+ * @property files - Every other file of the skill, root-relative.
+ */
+export interface SkillLayout {
+    readonly directory: string;
+    readonly skillFile: string;
+    readonly files: string[];
+}
+/**
+ * Tells whether a file lies in a directory or below it.
+ *
+ * @param file - Root-relative POSIX path.
+ * @param directory - Root-relative POSIX directory. `''` is the root and holds every file.
+ */
+export declare function isInside(file: string, directory: string): boolean;
+/** Directories of AI tools that hold installed skills. A `SKILL.md` elsewhere in a repository is a doc. */
+export declare const AI_DIRECTORIES: readonly string[];
+/**
+ * @brief Tells whether a file is inside the directory of an AI tool, such as `.claude/skills/deploy/SKILL.md`.
+ *
+ * @param file - Root-relative POSIX path.
+ */
+export declare function isInAiDirectory(file: string): boolean;
+/**
+ * @brief Finds the skills in a file list. A skill is a directory with a `SKILL.md` inside the directory of
+ * an AI tool, see `AI_DIRECTORIES`. Each file belongs to the deepest skill directory around it.
+ *
+ * @param files - Root-relative POSIX paths.
+ * @param anywhere - Counts a `SKILL.md` outside an AI directory too, for a directory the reader names as skills.
+ * @returns One layout per `SKILL.md`, deepest directory first.
+ */
+export declare function skillLayouts(files: readonly string[], anywhere?: boolean): SkillLayout[];
+/**
+ * @brief Finds the files of a list that belong to a skill, `SKILL.md` files included.
+ *
+ * @param files - Root-relative POSIX paths.
+ * @param anywhere - Counts a `SKILL.md` outside an AI directory too, as `skillLayouts` does.
+ * @returns The `SKILL.md` files and the other files of every skill in the list.
+ */
+export declare function skillOwnedFiles(files: readonly string[], anywhere?: boolean): Set<string>;

package/dist/scanner/skills/planner.d.ts

@@ -0,0 +1,61 @@
+import type { NodeRef } from '../../model';
+import type { CodePlanner } from '../code/planner';
+import type { FileRenderer } from '../content';
+import { type Source } from '../files';
+import type { GraphBuilder } from '../graph/builder';
+import type { ProseResolvers } from '../markdown/links';
+import type { SpecPlanner } from '../specs';
+/**
+ * @brief Adds skills to the graph. A skill is its `SKILL.md`. The other files of its
+ * directory become its descendants, each with the kind its place and type
+ * give it. A file that is an OpenAPI document or a JSON Schema goes to the
+ * `SpecPlanner`, a source file to the `CodePlanner`.
+ *
+ * Holds the graph, the file renderer, the code planner, the prose resolvers
+ * and the spec planner. Created and run by `RepositoryScanner` once per scan.
+ *
+ * @example
+ * await new SkillPlanner(graph, files, code, resolvers, specs).plan(sections.skills, input.skills);
+ */
+export declare class SkillPlanner {
+    private readonly graph;
+    private readonly files;
+    private readonly code;
+    private readonly resolvers;
+    private readonly specs;
+    /**
+     * Creates a planner.
+     *
+     * @param graph - Receives the skill, folder and file nodes.
+     * @param files - Renders the `SKILL.md` and the other files.
+     * @param code - Plans the source files of skills.
+     * @param resolvers - Links what the skill files refer to.
+     * @param specs - Plans the JSON and YAML files that are specs.
+     */
+    constructor(graph: GraphBuilder, files: FileRenderer, code: CodePlanner, resolvers: ProseResolvers, specs: SpecPlanner);
+    /**
+     * Adds the skills of every source, sorted by name, each with a unique slug.
+     *
+     * @param section - Node of the skills section, the parent of every skill.
+     * @param sources - Sources to read the skills from, each with the files it holds.
+     */
+    plan(section: NodeRef, sources: readonly Source[]): Promise<void>;
+    /**
+     * @brief Reads the `SKILL.md` of a skill and picks its name: the `name` field of
+     * the frontmatter, else the first `#` heading, else the directory name.
+     *
+     * @param source - Source the skill is in.
+     * @param layout - Files of the skill.
+     * @returns The skill with its text and name.
+     */
+    private read;
+    /**
+     * @brief Adds one skill node and a node for each of its files, under folder nodes
+     * that mirror the skill directory.
+     *
+     * @param section - Node of the skills section, the parent of the skill.
+     * @param skill - The skill as read from disk.
+     * @param slugs - Slugs already taken by other skills. Receives the slug of this one.
+     */
+    private planSkill;
+}

package/dist/scanner/specs.d.ts

@@ -0,0 +1,56 @@
+import type { NodeRef } from '../model';
+import type { DocFile } from './docs';
+import type { OpenApiPlanner } from './openapi/planner';
+import { type Reporter } from './reporter';
+import { type JsonObject } from './schema/describe';
+import type { JsonSchemaPlanner } from './schema/planner';
+/**
+ * Kind of a spec: a JSON or YAML file that describes data or an API in a
+ * standard format: an OpenAPI document or a JSON Schema.
+ */
+export type SpecKind = 'openapi' | 'json-schema';
+/**
+ * Tells what kind of spec a parsed file is.
+ *
+ * @param path - Path of the file, whose name is checked against the schema names.
+ * @param document - The parsed file.
+ * @returns `openapi` for a document with an `openapi` version 3 and paths, components or webhooks. `json-schema` for a document whose `$schema` names JSON Schema, or that is named like a schema and uses its keywords. `null` for anything else.
+ */
+export declare function specKind(path: string, document: JsonObject): SpecKind | null;
+/**
+ * @brief Adds the specs among the JSON and YAML files of a scan to the graph.
+ *
+ * Used by `DocPlanner` and `SkillPlanner` for every JSON or YAML file, before
+ * they add the file as plain text. The file is parsed once here, and goes to
+ * the planner of its kind. Created by `RepositoryScanner` for every scan.
+ */
+export declare class SpecPlanner {
+    private readonly openapi;
+    private readonly schemas;
+    private readonly reporter;
+    /**
+     * Keeps the planner of each spec kind.
+     *
+     * @param openapi - Plans OpenAPI documents.
+     * @param schemas - Plans JSON Schemas.
+     * @param reporter - Receives files that cannot be read.
+     */
+    constructor(openapi: OpenApiPlanner, schemas: JsonSchemaPlanner, reporter?: Reporter);
+    /** Tells whether a file can be a spec: true for a JSON or YAML file. */
+    handles(path: string): boolean;
+    /**
+     * Reads one file and adds it when it is a spec.
+     *
+     * @param file - The file to read, with its root and path.
+     * @param parent - Gives the folder or skill the file is in. Called only for a spec, so a folder with nothing else in it is not added.
+     * @returns The node of the file, or `null` when the file is no spec or cannot be parsed.
+     */
+    plan(file: DocFile, parent: () => NodeRef): Promise<NodeRef | null>;
+    /**
+     * Parses a file.
+     *
+     * @param file - The file to read, with its root and path.
+     * @returns The parsed object, or `null` for a file that is too large, holds no object or is not valid.
+     */
+    private read;
+}

package/dist/scanner/sql/catalog.d.ts

@@ -0,0 +1,98 @@
+import type { NodeRef } from '../../model';
+import type { SourceFile } from '../code/planner';
+import type { GraphBuilder } from '../graph/builder';
+import type { CodeHighlighter } from '../highlight';
+import type { ProseResolvers } from '../markdown/links';
+import type { MarkdownRenderer } from '../markdown/renderer';
+import type { ParsedQuery } from './query';
+import { type TableRegistry } from './registry';
+/**
+ * One SQL file of a catalog with the entries it holds.
+ *
+ * @property file - The SQL file, with its root and paths.
+ * @property queries - Entries from `parseQueryFile`. Not empty.
+ */
+export interface CatalogFile {
+    readonly file: SourceFile;
+    readonly queries: readonly ParsedQuery[];
+}
+/**
+ * Where a catalog goes in the tree and what it is called.
+ *
+ * @property parent - Folder or section the catalog goes in.
+ * @property name - Name the catalog is shown under.
+ * @property slug - Segment of the route of the catalog, when it is not the name.
+ * @property path - Path of the directory of the catalog, as the site shows it.
+ */
+export interface CatalogPlace {
+    readonly parent: NodeRef;
+    readonly name: string;
+    readonly slug?: string;
+    readonly path: string;
+}
+/**
+ * @brief Adds query catalogs to the graph: one `catalog` node per directory, one
+ * `query` node per entry, one `parameter` node per placeholder and one
+ * `field` node per column of the rows an entry returns. A table an entry
+ * names becomes a `reads` or a `writes` edge to that table.
+ *
+ * `DatabasePlanner` calls `add` once per directory that holds SQL files
+ * without tables. Tables and columns are looked up when the content of the
+ * graph is built, so a query can name a table of any file of the scan.
+ * `RepositoryScanner` creates one per scan with the `TableRegistry` it shares
+ * with the `SqlPlanner`; `DatabasePlanner` shows the wiring.
+ */
+export declare class CatalogPlanner {
+    private readonly graph;
+    private readonly markdown;
+    private readonly highlighter;
+    private readonly resolvers;
+    private readonly tables;
+    /**
+     * Creates a planner.
+     *
+     * @param graph - Receives the catalog, entry, parameter and field nodes.
+     * @param markdown - Renders the notes of entries.
+     * @param highlighter - Highlights the SQL of entries.
+     * @param resolvers - Links what notes refer to.
+     * @param tables - Finds the tables and columns that entries name.
+     */
+    constructor(graph: GraphBuilder, markdown: MarkdownRenderer, highlighter: CodeHighlighter, resolvers: ProseResolvers, tables: TableRegistry);
+    /**
+     * Adds one catalog with its entries.
+     *
+     * @param place - Where the catalog goes in the tree and what it is called.
+     * @param files - The SQL files of the catalog, in display order.
+     * @returns The node of the catalog.
+     */
+    add(place: CatalogPlace, files: readonly CatalogFile[]): NodeRef;
+    /**
+     * Adds one entry with its placeholders and its result columns.
+     *
+     * @param catalog - Node of the catalog.
+     * @param file - The SQL file the entry is in.
+     * @param query - The entry as parsed.
+     * @param anchors - Anchors the catalog uses already. The anchor of the entry is added.
+     * @returns The node of the entry.
+     */
+    private addQuery;
+    /**
+     * Finds the table column a column of a statement means.
+     *
+     * @param ref - The column as the statement names it, or `null`.
+     * @param query - The entry the statement is in.
+     * @param path - Display path (`SourceFile.displayPath`) of the file of the entry.
+     * @returns The column of the named table. For a column without a table in front: the column of that name when exactly one table of the entry has it. Else `null`.
+     */
+    private columnOf;
+    /**
+     * @brief Replaces `*` and `t.*` in the result columns of an entry by the columns
+     * of the tables they stand for. That needs the tables at the time the
+     * entry is added, so `DatabasePlanner` adds schema files first.
+     *
+     * @param query - The entry whose result columns are expanded.
+     * @param path - Display path (`SourceFile.displayPath`) of the file of the entry.
+     * @returns The result columns, with every star replaced whose tables the scan has. Any other star stays.
+     */
+    private expand;
+}

package/dist/scanner/sql/cursor.d.ts

@@ -0,0 +1,112 @@
+import type { SqlToken } from './tokens';
+/**
+ * @brief Error for a statement that cannot be read. Thrown by `TokenCursor` and by
+ * the readers of `parse.ts`. `parseSqlSchema` catches it and skips the statement.
+ */
+export declare class SqlSyntaxError extends Error {
+}
+/**
+ * @brief Walks the tokens of one statement. Holds the tokens, the SQL text they come
+ * from and the position of the cursor. The functions of `parse.ts` that read a
+ * statement, a column or a constraint each take a cursor, read what they know
+ * and leave the cursor behind it. `parseSqlSchema` creates one per statement,
+ * and `over` creates one for a part of a statement.
+ */
+export declare class TokenCursor {
+    private readonly tokens;
+    private readonly source;
+    private index;
+    /**
+     * Creates a cursor at the first token.
+     *
+     * @param tokens - The tokens to walk, in order.
+     * @param source - The SQL text the tokens come from, for reading text back as written.
+     */
+    constructor(tokens: readonly SqlToken[], source: string);
+    /**
+     * Tells whether every token is taken.
+     */
+    get done(): boolean;
+    /**
+     * Looks at a token without taking it.
+     *
+     * @param offset - Tokens ahead of the current one.
+     * @returns The token, or `undefined` behind the end.
+     */
+    peek(offset?: number): SqlToken | undefined;
+    /**
+     * Takes the current token.
+     *
+     * @returns The token the cursor was on.
+     * @throws {SqlSyntaxError} At the end of the statement.
+     */
+    next(): SqlToken;
+    /**
+     * Tells whether the current token is one of the given keywords.
+     *
+     * @param words - Keywords in capitals.
+     * @param offset - Tokens ahead of the current one.
+     * @returns True for an unquoted word that is one of them, whatever its case.
+     */
+    isWord(words: readonly string[], offset?: number): boolean;
+    /**
+     * Takes the tokens ahead when they are the given keywords in this order.
+     *
+     * @param words - Keywords in capitals.
+     * @returns True when all were there and are taken. False leaves the cursor in place.
+     */
+    accept(...words: string[]): boolean;
+    /**
+     * Tells whether the current token is a given symbol.
+     *
+     * @param symbol - One character.
+     */
+    isSymbol(symbol: string): boolean;
+    /**
+     * Takes the current token when it is a given symbol.
+     *
+     * @param symbol - One character.
+     */
+    acceptSymbol(symbol: string): boolean;
+    /**
+     * Takes a name: an unquoted word, a quoted identifier or a string.
+     *
+     * @returns The name without quotes.
+     * @throws {SqlSyntaxError} When the current token cannot be a name.
+     */
+    name(): string;
+    /**
+     * Takes a name that may have a schema in front, as in `main.booking`.
+     *
+     * @returns The last part of the name.
+     */
+    qualifiedName(): string;
+    /**
+     * Takes a group in parentheses with everything inside it.
+     *
+     * @returns The tokens between the parentheses.
+     * @throws {SqlSyntaxError} When the current token opens no group, or the group never closes.
+     */
+    group(): SqlToken[];
+    /**
+     * Reads SQL back as written, with runs of whitespace as one space.
+     *
+     * @param from - First token of the text.
+     * @param to - Last token of the text. Defaults to the token in front of the cursor.
+     */
+    text(from: SqlToken, to?: SqlToken | undefined): string;
+    /**
+     * Creates a cursor for some of the tokens of the same text.
+     *
+     * @param tokens - Tokens of part of the statement, from the same text.
+     * @returns A cursor at the first of them.
+     */
+    over(tokens: readonly SqlToken[]): TokenCursor;
+}
+/**
+ * Splits tokens at the commas that are not inside parentheses.
+ *
+ * @param tokens - Tokens of a list, without the parentheses around it.
+ * @returns The tokens of each item. An empty item is left out.
+ */
+export declare function splitAtCommas(tokens: readonly SqlToken[]): SqlToken[][];

package/dist/scanner/sql/database.d.ts

@@ -0,0 +1,51 @@
+import type { NodeRef } from '../../model';
+import { type Source } from '../files';
+import type { GraphBuilder } from '../graph/builder';
+import { type Reporter } from '../reporter';
+import type { CatalogPlanner } from './catalog';
+import type { SqlPlanner } from './planner';
+/**
+ * @brief Builds the database section from the SQL files of a directory tree.
+ *
+ * A file that creates a table is a schema and goes to the `SqlPlanner`.
+ * Every other SQL file holds queries and statements. The files of one
+ * directory form a catalog, which goes to the `CatalogPlanner`. The section
+ * starts at the directory the SQL files share.
+ *
+ * `RepositoryScanner` creates one per scan and calls `planTree` once per
+ * source directory. The `SqlPlanner` and the `CatalogPlanner` share one
+ * `TableRegistry`, so queries can find the tables of schema files.
+ *
+ * @example
+ * const tables = new TableRegistry();
+ * const sql = new SqlPlanner(graph, markdown, highlighter, resolvers, tables, reporter);
+ * const databases = new DatabasePlanner(
+ *   graph,
+ *   sql,
+ *   new CatalogPlanner(graph, markdown, highlighter, resolvers, tables),
+ *   reporter,
+ * );
+ * await databases.planTree(section, source);
+ */
+export declare class DatabasePlanner {
+    private readonly graph;
+    private readonly schemas;
+    private readonly catalogs;
+    private readonly reporter;
+    /**
+     * Creates a planner.
+     *
+     * @param graph - Receives the database section nodes.
+     * @param schemas - Plans the schema files.
+     * @param catalogs - Plans the query catalogs.
+     * @param reporter - Receives files that cannot be read.
+     */
+    constructor(graph: GraphBuilder, schemas: SqlPlanner, catalogs: CatalogPlanner, reporter?: Reporter);
+    /**
+     * Adds every SQL file of `source` below `section`.
+     *
+     * @param section - Node of the database section.
+     * @param source - The SQL files to read, with their root and prefix.
+     */
+    planTree(section: NodeRef, source: Source): Promise<void>;
+}

package/dist/scanner/sql/parse.d.ts

@@ -0,0 +1,122 @@
+/**
+ * What a `REFERENCES` clause states.
+ *
+ * @property table - Name of the referenced table.
+ * @property columns - Referenced columns. Empty when the clause names none, which means the primary key.
+ * @property onDelete - Action in capitals, or `''`.
+ * @property onUpdate - Action in capitals, or `''`.
+ */
+export interface ParsedReference {
+    readonly table: string;
+    readonly columns: readonly string[];
+    readonly onDelete: string;
+    readonly onUpdate: string;
+}
+/**
+ * A foreign key of a table, from a column or from a table constraint.
+ *
+ * @property name - Name of the constraint, or `''`.
+ * @property sourceColumns - Columns of the table that hold the key.
+ */
+export interface ParsedForeignKey extends ParsedReference {
+    readonly name: string;
+    readonly sourceColumns: readonly string[];
+}
+/**
+ * One column of a table as its statement writes it.
+ *
+ * @property name - Name of the column.
+ * @property type - Declared type as written, with single spaces. `''` for a column without one.
+ * @property notNull - True when the column is declared `NOT NULL`.
+ * @property defaultValue - Default value as written, or `null`.
+ * @property constraints - Other constraints of the column as written, such as `UNIQUE`, `CHECK (n > 0)` or `COLLATE NOCASE`.
+ * @property description - Markdown from the comment behind or above the column.
+ */
+export interface ParsedColumn {
+    readonly name: string;
+    readonly type: string;
+    readonly notNull: boolean;
+    readonly defaultValue: string | null;
+    readonly constraints: readonly string[];
+    readonly description: string;
+}
+/**
+ * An index of a table, from a `CREATE INDEX` statement.
+ *
+ * @property name - Name of the index.
+ * @property columns - Indexed columns or expressions as written.
+ * @property unique - True for a `UNIQUE` index.
+ */
+export interface ParsedIndex {
+    readonly name: string;
+    readonly columns: readonly string[];
+    readonly unique: boolean;
+}
+/**
+ * One table of a schema.
+ *
+ * @property name - Name of the table.
+ * @property line - 1-based line of the statement.
+ * @property description - Markdown from the comment above the statement.
+ * @property columns - Columns of the table.
+ * @property primaryKey - Columns of the primary key, in key order.
+ * @property foreignKeys - Foreign keys of the table.
+ * @property constraints - Table constraints that are no key, as written.
+ * @property options - `WITHOUT ROWID`, `STRICT`, `VIRTUAL`, `TEMPORARY`.
+ * @property indexes - Indexes of the table.
+ */
+export interface ParsedTable {
+    readonly name: string;
+    readonly line: number;
+    readonly description: string;
+    readonly columns: readonly ParsedColumn[];
+    readonly primaryKey: readonly string[];
+    readonly foreignKeys: readonly ParsedForeignKey[];
+    readonly constraints: readonly string[];
+    readonly options: readonly string[];
+    readonly indexes: readonly ParsedIndex[];
+}
+/**
+ * A view or a trigger of a schema.
+ *
+ * @property kind - `view` or `trigger`.
+ * @property name - Name of the view or trigger.
+ * @property table - The table a trigger fires on. `''` for a view.
+ * @property line - 1-based line of the statement.
+ * @property description - Markdown from the comment above the statement.
+ * @property sql - The statement as written, without the closing semicolon.
+ */
+export interface ParsedObject {
+    readonly kind: 'view' | 'trigger';
+    readonly name: string;
+    readonly table: string;
+    readonly line: number;
+    readonly description: string;
+    readonly sql: string;
+}
+/**
+ * What a schema file declares, from `parseSqlSchema`.
+ *
+ * @property intro - Markdown from the comments that open the file.
+ * @property tables - Tables the file creates, in file order.
+ * @property objects - Views and triggers the file creates, in file order.
+ */
+export interface ParsedSchema {
+    readonly intro: string;
+    readonly tables: readonly ParsedTable[];
+    readonly objects: readonly ParsedObject[];
+}
+/**
+ * @brief Reads the tables, indexes, views and triggers of a SQLite schema file.
+ * Statements of any other kind, and statements that cannot be read, are
+ * skipped. The SQL is read as text and never run.
+ *
+ * A comment directly above a statement describes its table, view or trigger.
+ * A comment behind a column on the same line, or directly above it, describes
+ * the column. The comments that open the file, apart from the first
+ * statement, are the introduction.
+ *
+ * @param source - Text of the file.
+ * @returns What the file declares, in file order.
+ */
+export declare function parseSqlSchema(source: string): ParsedSchema;

package/dist/scanner/sql/planner.d.ts

@@ -0,0 +1,69 @@
+import type { NodeRef } from '../../model';
+import type { SourceFile } from '../code/planner';
+import type { GraphBuilder } from '../graph/builder';
+import type { CodeHighlighter } from '../highlight';
+import type { ProseResolvers } from '../markdown/links';
+import type { MarkdownRenderer } from '../markdown/renderer';
+import { type Reporter } from '../reporter';
+import { type ParsedSchema } from './parse';
+import type { TableRegistry } from './registry';
+/**
+ * @brief Adds SQL schema files to the graph: one `database` node per file, one
+ * `table` node per table and one `field` node per column. A foreign key
+ * becomes a `references` edge from its table to the table it points at.
+ *
+ * `DatabasePlanner` calls `add` for every schema file of the repository, and
+ * `CodePlanner` calls `plan` for a `.sql` file that belongs to a skill.
+ * `RepositoryScanner` creates one per scan with the `TableRegistry` it shares
+ * with the `CatalogPlanner`; `DatabasePlanner` shows the wiring.
+ */
+export declare class SqlPlanner {
+    private readonly graph;
+    private readonly markdown;
+    private readonly highlighter;
+    private readonly resolvers;
+    private readonly tables;
+    private readonly reporter;
+    /**
+     * Creates a planner.
+     *
+     * @param graph - Receives the database, table and field nodes.
+     * @param markdown - Renders comments.
+     * @param highlighter - Highlights the statements of views and triggers.
+     * @param resolvers - Links what comments refer to.
+     * @param tables - Receives every table with its columns, and finds the targets of foreign keys.
+     * @param reporter - Receives files that cannot be read.
+     */
+    constructor(graph: GraphBuilder, markdown: MarkdownRenderer, highlighter: CodeHighlighter, resolvers: ProseResolvers, tables: TableRegistry, reporter?: Reporter);
+    /**
+     * Tells whether a file is SQL: its extension is `.sql`, in any case.
+     */
+    handles(path: string): boolean;
+    /**
+     * Reads one SQL file and adds its nodes when it creates a table.
+     *
+     * @param file - The SQL file to read.
+     * @param parent - Gives the folder or skill the file is in. Called only when the file creates a table, so a folder with nothing else in it is not added.
+     * @returns The node of the file, or `null` when it creates no table or cannot be read.
+     */
+    plan(file: SourceFile, parent: () => NodeRef): Promise<NodeRef | null>;
+    /**
+     * Adds the nodes of one schema file.
+     *
+     * @param file - The SQL file to add.
+     * @param schema - What the file declares, from `parseSqlSchema`.
+     * @param parent - The folder or skill the file is in.
+     * @returns The node of the file.
+     */
+    add(file: SourceFile, schema: ParsedSchema, parent: NodeRef): NodeRef;
+    /**
+     * @brief Resolves a foreign key against the tables of the scan, and records the
+     * edge to its target.
+     *
+     * @param from - Node of the table that holds the key.
+     * @param key - The foreign key as the statement wrote it.
+     * @param path - Display path (`SourceFile.displayPath`) of the file the key is in.
+     * @returns The key with its target, and with the primary key of the target as its columns when the statement names none.
+     */
+    private foreignKey;
+}