@g3nomaly/analyze 0.1.0 → 0.1.1

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

@@ -7,7 +7,7 @@ import type { DefinitionPlanner } from '../schema/definitions';
 import { type JsonObject } from '../schema/describe';
 import type { DefinitionRegistry } from '../schema/registry';
 /**
- * Adds an OpenAPI document to the graph: one `api` node for the document,
+ * @brief Adds an OpenAPI document to the graph: one `api` node for the document,
  * one `operation` node per method on a path and per webhook, one `parameter`
  * node per parameter, and one definition per entry of `components.schemas`.
  *
@@ -28,55 +28,67 @@ export declare class OpenApiPlanner {
     private readonly definitions;
     private readonly registry;
     /**
-     * Creates a planner.
+     * @brief Creates a planner.
      *
+     * @param graph - Receives the API, operation and parameter nodes and their edges.
+     * @param markdown - Renders the descriptions.
      * @param resolvers - Links what descriptions refer to.
      * @param definitions - Adds the schema definitions and links type expressions.
      * @param registry - Receives the document, so refs to it from other files resolve.
      */
     constructor(graph: GraphBuilder, markdown: MarkdownRenderer, resolvers: ProseResolvers, definitions: DefinitionPlanner, registry: DefinitionRegistry);
     /**
-     * Adds one OpenAPI document.
+     * @brief Adds one OpenAPI document.
      *
      * @param parent - Folder or skill the file is in.
+     * @param file - The file: its root, path, display path and prefix.
      * @param document - The parsed file.
      * @returns The node of the document.
      */
     plan(parent: NodeRef, file: DocFile, document: JsonObject): NodeRef;
     /**
-     * Renders the tags a document declares, in document order, each with its description.
+     * @brief Renders the tags a document declares, in document order, each with its description.
      *
+     * @param document - The parsed document.
      * @param node - Node of the document.
+     * @param file - The file the document is in.
+     * @returns The tags, with their descriptions rendered as HTML.
      */
     private tags;
     /**
-     * Adds one operation with its parameters.
+     * @brief Adds one operation with its parameters.
      *
      * @param owner - The document the operation is in.
      * @param document - The parsed document, for resolving refs.
+     * @param found - The operation as found in the document.
      */
     private planOperation;
     /**
-     * Reads the request body of an operation.
+     * @brief Reads the request body of an operation.
      *
      * @param document - The parsed document, for resolving refs.
+     * @param operation - The operation object of the document.
      * @param node - Node of the operation. Schemas of the body become `type` edges from it.
+     * @param file - The file the document is in.
      * @returns The body, or `null` for an operation without one.
      */
     private requestBody;
     /**
-     * Reads the responses of an operation.
+     * @brief Reads the responses of an operation.
      *
      * @param document - The parsed document, for resolving refs.
+     * @param operation - The operation object of the document.
+     * @param file - The file the document is in.
      * @param node - Node of the operation. A schema of a response becomes a `returns` edge from it, or a `throws` edge for an error.
      * @returns The responses in document order.
      */
     private responses;
     /**
-     * Reads the media types of a request body or a response.
+     * @brief Reads the media types of a request body or a response.
      *
      * @param content - The `content` object: media type to media type object.
      * @param node - Node of the operation.
+     * @param file - The file the document is in.
      * @param relation - Kind of the edge a schema records from the operation.
      * @returns One entry per media type, in document order.
      */

package/dist/scanner/packages.d.ts

@@ -0,0 +1,28 @@
+import type { PackageRole } from '../model';
+import type { Source } from './files';
+/**
+ * @brief A directory with a package manifest, as `detectPackages` reads it.
+ *
+ * @property packageName - Name the manifest gives, such as `@g3nomaly/core`, or the directory name when it gives none.
+ * @property role - `app`, `library` or `workspace`. A manifest that declares an executable makes an app; otherwise a directory named `apps`/`app` above it makes an app, one named `libs`/`lib` a library, and else the manifest decides.
+ * @property manifest - Display path of the manifest that marks the package, such as `packages/core/package.json`.
+ * @property version - Version the manifest gives, or `null`.
+ * @property description - Description the manifest gives, or `''`.
+ */
+export interface PackageInfo {
+    readonly packageName: string;
+    readonly role: PackageRole;
+    readonly manifest: string;
+    readonly version: string | null;
+    readonly description: string;
+}
+/**
+ * @brief Finds the packages of a set of sources: every directory below a root with a manifest that one of the readers understands.
+ *
+ * A directory with several manifests is read by the first reader in `READERS` that understands one. The root
+ * directory of a source is left out: it is the repository itself.
+ *
+ * @param sources - Directories with their files, such as the code sources of a scan.
+ * @returns Packages by display path of their directory, such as `packages/core`.
+ */
+export declare function detectPackages(sources: readonly Source[]): Promise<Map<string, PackageInfo>>;

package/dist/scanner/reporter.d.ts

@@ -1,6 +1,9 @@
-/** Receives problems that should not stop a scan. */
+/**
+ * @brief Receives problems that should not stop a scan.
+ *
+ * @property warn - Reports one problem, as one line of plain text.
+ */
 export interface Reporter {
-    /** Reports one problem, as one line of plain text. */
     warn(message: string): void;
 }
 /** A reporter that drops every warning. */

package/dist/scanner/scanner.d.ts

@@ -4,26 +4,35 @@ import type { CodeHighlighter } from './highlight';
 import { type Reporter } from './reporter';
 import { type TaskTreeSource } from './tasks/planner';
 /**
- * The directories one scan reads. Skills and docs each have their own. The
+ * @brief The directories one scan reads. Skills and docs each have their own. The
  * code section and the database section are both read from `code`: source
  * files go to the one, SQL files to the other.
+ *
+ * @property skills - Directories of the skills section.
+ * @property docs - Directories of the docs section.
+ * @property code - Directories of the code and database sections.
+ * @property tasks - The task-manager trees. Their files are shown in the tasks section, and nowhere else.
  */
 export interface ScanInput {
     readonly skills: readonly Source[];
     readonly docs: readonly Source[];
     readonly code: readonly Source[];
-    /** The task-manager trees. Their files are shown in the tasks section, and nowhere else. */
     readonly tasks: readonly TaskTreeSource[];
 }
-/** What a {@link RepositoryScanner} is built with. */
+/**
+ * @brief What a {@link RepositoryScanner} is built with.
+ *
+ * @property grammarDir - Directory that relative grammar paths resolve against.
+ * @property highlighter - Highlights the code blocks of the markdown.
+ * @property reporter - Receives problems that do not stop a scan. Defaults to `silentReporter`.
+ */
 export interface ScannerOptions {
-    /** Directory that relative grammar paths resolve against. */
     readonly grammarDir: string;
     readonly highlighter: CodeHighlighter;
     readonly reporter?: Reporter;
 }
 /**
- * Turns directories into the graph of a documentation site. Holds the parts
+ * @brief Turns directories into the graph of a documentation site. Holds the parts
  * that outlive one scan: the language registry, the symbol extractor, the
  * grammar loader and the markdown and file renderers. Each scan builds a fresh
  * graph and wires up every planner for it. Created in `api/services.ts` and
@@ -40,12 +49,17 @@ export declare class RepositoryScanner {
     private readonly grammars;
     private readonly markdown;
     private readonly files;
-    /** Creates the grammar loader and the renderers the scans share. */
+    /**
+     * @brief Creates the grammar loader and the renderers the scans share.
+     *
+     * @param options - Grammar directory, highlighter and optional reporter.
+     */
     constructor(options: ScannerOptions);
     /**
-     * Scans the directories of every section into one graph: skills, docs,
+     * @brief Scans the directories of every section into one graph: skills, docs,
      * code, database and tasks, in that order.
      *
+     * @param input - The directories of each section.
      * @returns The nodes and edges of the bundle, without its meta and semantic index.
      */
     scan(input: ScanInput): Promise<Pick<DocsBundle, 'nodes' | 'edges'>>;

package/dist/scanner/schema/definitions.d.ts

@@ -5,16 +5,20 @@ import type { ProseResolvers } from '../markdown/links';
 import type { MarkdownRenderer } from '../markdown/renderer';
 import { type TypeExpression } from './describe';
 import type { DefinitionRegistry } from './registry';
-/** The file a definition is in. */
+/**
+ * @brief The file a definition is in.
+ *
+ * @property ref - Node of the file. Definitions become its children.
+ * @property file - The file the definitions are in.
+ * @property anchors - Anchors already used on the page of the file.
+ */
 export interface DefinitionOwner {
-    /** Node of the file. Definitions become its children. */
     readonly ref: NodeRef;
     readonly file: DocFile;
-    /** Anchors already used on the page of the file. */
     readonly anchors: Set<string>;
 }
 /**
- * Adds named JSON Schemas to the graph: one `definition` node per schema and
+ * @brief Adds named JSON Schemas to the graph: one `definition` node per schema and
  * one `field` node per property. A `$ref` in a type becomes a link to the
  * definition it names, and an edge: `type` from a property, `extends` from a
  * definition.
@@ -35,23 +39,28 @@ export declare class DefinitionPlanner {
     private readonly resolvers;
     private readonly registry;
     /**
-     * Creates a planner.
+     * @brief Creates a planner.
      *
+     * @param graph - Receives the definition and field nodes and their edges.
+     * @param markdown - Renders the descriptions.
      * @param resolvers - Links what descriptions refer to.
      * @param registry - Receives every definition, and finds the targets of refs.
      */
     constructor(graph: GraphBuilder, markdown: MarkdownRenderer, resolvers: ProseResolvers, registry: DefinitionRegistry);
     /**
-     * Adds one definition with its properties.
+     * @brief Adds one definition with its properties.
      *
+     * @param owner - The file the definition is in.
      * @param name - Name of the definition, as the page shows it.
      * @param pointer - JSON pointer of the schema inside its file. Refs to that place link to the definition.
+     * @param schema - The schema: an object, or `true` or `false`.
      * @returns The node of the definition.
      */
     add(owner: DefinitionOwner, name: string, pointer: string, schema: unknown): NodeRef;
     /**
-     * Turns a type expression into text with links to the definitions its refs name.
+     * @brief Turns a type expression into text with links to the definitions its refs name.
      *
+     * @param expression - The type expression, with the spans of its refs.
      * @param from - Node the expression belongs to.
      * @param file - The file the expression is in. A relative ref starts there.
      * @param relation - Kind of the edge each resolved ref records from `from`.
@@ -59,10 +68,11 @@ export declare class DefinitionPlanner {
      */
     linked(expression: TypeExpression, from: NodeRef, file: DocFile, relation: EdgeKind): LinkedText;
     /**
-     * Renders a description.
+     * @brief Renders a description as HTML.
      *
      * @param markdown - Markdown of the description, or `''`.
      * @param node - Node the description belongs to. Links in it become edges from this node.
+     * @param file - The file the description is in. Its root, path and prefix resolve links.
      * @returns HTML, or `''`.
      */
     html(markdown: string, node: NodeRef, { root, path, prefix }: DocFile): Promise<string>;

package/dist/scanner/schema/describe.d.ts

@@ -1,62 +1,86 @@
 /** A JSON object as parsed from JSON or YAML. */
 export type JsonObject = Readonly<Record<string, unknown>>;
 /**
- * Tells a JSON object from every other value: true for an object that is no
+ * @brief Tells a JSON object from every other value: true for an object that is no
  * array and not `null`.
+ *
+ * @param value - Any value, as parsed from JSON or YAML.
  */
 export declare function isJsonObject(value: unknown): value is JsonObject;
-/** A span of a type expression that stands for a `$ref`. */
+/**
+ * @brief A span of a type expression that stands for a `$ref`.
+ *
+ * @property start - Offset in the type text where the span starts.
+ * @property end - Offset in the type text where the span ends.
+ * @property ref - The `$ref` as the schema writes it.
+ */
 export interface SchemaRef {
     readonly start: number;
     readonly end: number;
-    /** The `$ref` as the schema writes it. */
     readonly ref: string;
 }
-/** What a schema allows, as text: `string[]`, `Cat | Dog`, `"open" | "closed"`. */
+/**
+ * @brief What a schema allows, as text: `string[]`, `Cat | Dog`, `"open" | "closed"`.
+ *
+ * @property text - The type as text.
+ * @property refs - The spans of the text that are `$ref`s, in text order, not overlapping.
+ */
 export interface TypeExpression {
     readonly text: string;
-    /** In text order, not overlapping. */
     readonly refs: readonly SchemaRef[];
 }
-/** One property of an object schema. A nested property has a dotted name. */
+/**
+ * @brief One property of an object schema. A nested property has a dotted name.
+ *
+ * @property name - Name of the property, dotted for a nested one: `city`, `address.city`, `items[].sku`.
+ * @property type - The type of the property.
+ * @property required - True when the parent schema requires the property.
+ * @property defaultValue - The default as JSON, or `null`.
+ * @property description - Markdown.
+ * @property constraints - Keywords that narrow the type, as `keyword: value`.
+ */
 export interface SchemaProperty {
-    /** `city`, `address.city`, `items[].sku`. */
     readonly name: string;
     readonly type: TypeExpression;
     readonly required: boolean;
-    /** The default as JSON, or `null`. */
     readonly defaultValue: string | null;
-    /** Markdown. */
     readonly description: string;
-    /** Keywords that narrow the type, as `keyword: value`. */
     readonly constraints: readonly string[];
 }
-/** What a schema says, in the shape the site shows. */
+/**
+ * @brief What a schema says, in the shape the site shows.
+ *
+ * @property type - The type of the schema.
+ * @property description - Markdown.
+ * @property constraints - Keywords that narrow the type, as `keyword: value`.
+ * @property values - Values of an `enum` or a `const`, as JSON. Empty when they fit inside `type`.
+ * @property deprecated - True when the schema is deprecated.
+ * @property properties - Every property, nested ones included, in schema order.
+ */
 export interface SchemaDescription {
     readonly type: TypeExpression;
-    /** Markdown. */
     readonly description: string;
     readonly constraints: readonly string[];
-    /** Values of an `enum` or a `const`, as JSON. */
     readonly values: readonly string[];
     readonly deprecated: boolean;
     readonly properties: readonly SchemaProperty[];
 }
 /**
- * Reads the last part of a `$ref` as a name.
+ * @brief Reads the last part of a `$ref` as a name.
  *
  * @param ref - A `$ref`, such as `#/$defs/Booking` or `cargo.schema.json`.
  * @returns `Booking` for a ref into a file, the file name for a ref to a whole file.
  */
 export declare function refName(ref: string): string;
 /**
- * Decodes one segment of a JSON pointer.
+ * @brief Decodes one segment of a JSON pointer.
  *
+ * @param segment - One segment between two `/`, possibly percent-encoded.
  * @returns The key it names: percent escapes decoded, `~1` as `/` and `~0` as `~`.
  */
 export declare function decodePointerSegment(segment: string): string;
 /**
- * Writes what a schema allows as a type expression.
+ * @brief Writes what a schema allows as a type expression.
  *
  * @param schema - A schema: an object, or `true` or `false`.
  * @param depth - Nesting of the schema inside the one that is described.
@@ -64,7 +88,7 @@ export declare function decodePointerSegment(segment: string): string;
  */
 export declare function typeOf(schema: unknown, depth?: number): TypeExpression;
 /**
- * Describes a JSON Schema in the shape the site shows: a type expression, a
+ * @brief Describes a JSON Schema in the shape the site shows: a type expression, a
  * description, constraints and a flat list of properties.
  *
  * @param schema - The schema: an object, or `true` or `false`.
@@ -72,8 +96,10 @@ export declare function typeOf(schema: unknown, depth?: number): TypeExpression;
  */
 export declare function describeSchema(schema: unknown): SchemaDescription;
 /**
- * Tells whether a schema says anything about a value: true when it has a
+ * @brief Tells whether a schema says anything about a value: true when it has a
  * type, properties, a composition, values or a `$ref`. A file that only
  * holds `$defs` has a root schema that does not.
+ *
+ * @param schema - The schema to check.
  */
 export declare function describesValue(schema: JsonObject): boolean;

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

@@ -7,7 +7,7 @@ import type { DefinitionPlanner } from './definitions';
 import { type JsonObject } from './describe';
 import type { DefinitionRegistry } from './registry';
 /**
- * Adds a JSON Schema file to the graph: one `schema` node for the file, with
+ * @brief Adds a JSON Schema file to the graph: one `schema` node for the file, with
  * its text, and one definition per schema it names. The root schema is a
  * definition when it describes a value.
  *
@@ -28,17 +28,20 @@ export declare class JsonSchemaPlanner {
     private readonly definitions;
     private readonly registry;
     /**
-     * Creates a planner.
+     * @brief Creates a planner.
      *
+     * @param graph - Receives the schema and definition nodes and their edges.
      * @param files - Renders the text of the file.
      * @param resolvers - Links what the file refers to.
+     * @param definitions - Adds the definitions the schema names.
      * @param registry - Receives the file and its `$id`, so refs to the file resolve.
      */
     constructor(graph: GraphBuilder, files: FileRenderer, resolvers: ProseResolvers, definitions: DefinitionPlanner, registry: DefinitionRegistry);
     /**
-     * Adds one schema file.
+     * @brief Adds one schema file.
      *
      * @param parent - Folder or skill the file is in.
+     * @param file - The file: its root, path, display path and prefix.
      * @param schema - The parsed file.
      * @returns The node of the file.
      */

package/dist/scanner/schema/registry.d.ts

@@ -1,49 +1,56 @@
 import type { NodeRef } from '../../model';
 /**
- * Writes a JSON pointer in one spelling, so two spellings of one place compare equal.
+ * @brief Writes a JSON pointer in one spelling, so two spellings of one place compare equal.
  *
  * @param pointer - A pointer, with or without the `#` in front.
  * @returns The pointer with every segment decoded. `''` names the root.
  */
 export declare function normalizePointer(pointer: string): string;
-/** What a `$ref` points at. */
+/**
+ * @brief What a `$ref` points at.
+ *
+ * @property ref - The node that shows the place.
+ * @property name - Name of the node, as a type expression shows it.
+ */
 export interface RefTarget {
     readonly ref: NodeRef;
-    /** Name of the node, as a type expression shows it. */
     readonly name: string;
 }
 /**
- * Finds the nodes that `$ref`s point at, across the JSON Schema files and
+ * @brief Finds the nodes that `$ref`s point at, across the JSON Schema files and
  * OpenAPI documents of one scan.
  *
- * Holds a map from `path#pointer` to the node at that place, and a map from
- * `$id` to file path. Created once per scan by `RepositoryScanner` and shared
- * by `JsonSchemaPlanner`, `OpenApiPlanner` and `DefinitionPlanner`. The
- * planners register every file and definition when they add it;
- * `DefinitionPlanner` resolves refs when the content of the graph is built.
- * By then every file is read, so a ref can point into a later file.
+ * Created once per scan by `RepositoryScanner` and shared by `JsonSchemaPlanner`,
+ * `OpenApiPlanner` and `DefinitionPlanner`. The planners register every file and
+ * definition when they add it; `DefinitionPlanner` resolves refs when the content
+ * of the graph is built. By then every file is read, so a ref can point into a
+ * later file.
+ *
+ * @property places - The node at each `path#pointer` place.
+ * @property ids - Path of each schema file by its `$id`.
+ * @example
+ * const registry = new DefinitionRegistry();
  */
 export declare class DefinitionRegistry {
-    /** `path#pointer` to the node at that place. */
     private readonly places;
-    /** `$id` of a schema file to its path. */
     private readonly ids;
     /**
-     * Records the node that shows a place in a file.
+     * @brief Records the node that shows a place in a file.
      *
      * @param path - Path of the file, as the site shows it.
      * @param pointer - JSON pointer of the place inside the file. `''` is the whole file.
+     * @param target - The node that shows the place, and its name.
      */
     register(path: string, pointer: string, target: RefTarget): void;
     /**
-     * Records the `$id` of a schema file, so a ref by that id finds the file.
+     * @brief Records the `$id` of a schema file, so a ref by that id finds the file.
      *
      * @param id - The `$id`, an absolute URI.
      * @param path - Path of the file, as the site shows it.
      */
     registerId(id: string, path: string): void;
     /**
-     * Finds the node a `$ref` points at.
+     * @brief Finds the node a `$ref` points at.
      *
      * @param ref - The `$ref` as written: `#/$defs/Cargo`, `cargo.schema.json#/$defs/Cargo`, or the `$id` of a file.
      * @param fromPath - Path of the file the ref is in. A relative ref starts there.
@@ -51,7 +58,7 @@ export declare class DefinitionRegistry {
      */
     resolve(ref: string, fromPath: string): RefTarget | null;
     /**
-     * Finds the file a URI names.
+     * @brief Finds the file a URI names.
      *
      * @param uri - The part of a ref in front of the `#`.
      * @param fromPath - Path of the file the ref is in, as the site shows it.

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

@@ -2,7 +2,7 @@ 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';
 /**
- * Kind of a file in a skill, from where it is and what it is. The first rule that matches wins.
+ * @brief Classifies a file in a skill by where it is and what it is. The first rule that matches wins.
  *
  * | Rule | Kind |
  * |---|---|
@@ -16,5 +16,6 @@ export type SkillFileKind = Exclude<FileKind, 'skill' | 'document'> | 'source';
  *
  * @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

@@ -1,12 +1,15 @@
 /** 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. */
+/**
+ * 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 {
-    /** Root-relative directory of the `SKILL.md`. `''` for the root itself. */
     readonly directory: string;
-    /** Root-relative path of the `SKILL.md`. */
     readonly skillFile: string;
-    /** Every other file of the skill, root-relative. */
     readonly files: string[];
 }
 /**
@@ -16,13 +19,28 @@ export interface SkillLayout {
  * @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[];
 /**
- * Finds the skills in a file list. A skill is a directory with a `SKILL.md`.
- * Each file belongs to the deepest skill directory around it.
+ * @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[]): SkillLayout[];
-/** The files of a list that belong to a skill, `SKILL.md` files included. */
-export declare function skillOwnedFiles(files: readonly string[]): Set<string>;
+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

@@ -6,7 +6,7 @@ import type { GraphBuilder } from '../graph/builder';
 import type { ProseResolvers } from '../markdown/links';
 import type { SpecPlanner } from '../specs';
 /**
- * Adds skills to the graph. A skill is its `SKILL.md`. The other files of its
+ * @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`.
@@ -23,23 +23,38 @@ export declare class SkillPlanner {
     private readonly code;
     private readonly resolvers;
     private readonly specs;
-    /** Creates a planner. */
+    /**
+     * 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>;
     /**
-     * Reads the `SKILL.md` of a skill and picks its name: the `name` field of
+     * @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;
     /**
-     * Adds one skill node and a node for each of its files, under folder nodes
+     * @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;