@g3nomaly/analyze 0.1.0 → 0.1.2

package/dist/model/registry.d.ts

@@ -22,6 +22,13 @@ export declare const NodeGroupSchema: z.ZodMiniEnum<{
 export type NodeGroup = z.infer<typeof NodeGroupSchema>;
 /** What the registry states about one node kind. */
 export declare const NodeKindSpecSchema: z.ZodMiniObject<{
+    label: z.ZodMiniString<string>;
+    description: z.ZodMiniString<string>;
+    member: z.ZodMiniDefault<z.ZodMiniBoolean<boolean>>;
+}, z.core.$strict>;
+export type NodeKindSpec = z.infer<typeof NodeKindSpecSchema>;
+export declare const NodeTypeSpecSchema: z.ZodMiniObject<{
+    kind: z.ZodMiniString<string>;
     group: z.ZodMiniEnum<{
         entry: "entry";
         file: "file";
@@ -40,7 +47,7 @@ export declare const NodeKindSpecSchema: z.ZodMiniObject<{
     described: z.ZodMiniDefault<z.ZodMiniBoolean<boolean>>;
 }, z.core.$strict>;
 /** The parsed spec of one node kind, with defaults filled in. */
-export type NodeKindSpec = z.infer<typeof NodeKindSpecSchema>;
+export type NodeTypeSpec = z.infer<typeof NodeTypeSpecSchema>;
 /** What the registry states about one top-level section. */
 export declare const SectionSpecSchema: z.ZodMiniObject<{
     label: z.ZodMiniString<string>;
@@ -73,15 +80,15 @@ export type RelationKindSpec = z.infer<typeof RelationKindSpecSchema>;
 export declare const SECTION_REGISTRY: {
     readonly skills: {
         readonly label: 'Skills';
-        readonly description: 'Every `SKILL.md` and the files beside it.';
+        readonly description: 'Every `SKILL.md` inside the directory of an AI tool, such as `.claude`, and the files beside it.';
     };
     readonly docs: {
         readonly label: 'Docs';
-        readonly description: 'Markdown, JSON, OpenAPI documents and JSON Schemas.';
+        readonly description: 'Markdown files.';
     };
     readonly code: {
         readonly label: 'Code';
-        readonly description: 'Source files with their classes and functions.';
+        readonly description: 'Source files with their classes and functions, and JSON, TOML and YAML files, OpenAPI documents and JSON Schemas among them.';
     };
     readonly database: {
         readonly label: 'Database';
@@ -92,99 +99,237 @@ export declare const SECTION_REGISTRY: {
         readonly description: 'Plans, their phases and their tasks, as task-manager keeps them.';
     };
 };
-/** Every node kind, in the order the site lists kinds. */
+/**
+ * Every node kind, in the order filters and legends list them. Each node type of `NODE_TYPE_REGISTRY` belongs to one.
+ * A `member` kind is found by search and filters, which return the node it belongs to instead.
+ */
 export declare const NODE_KIND_REGISTRY: {
+    readonly folder: {
+        readonly label: 'folder';
+        readonly description: 'A directory of the repository.';
+    };
+    readonly package: {
+        readonly label: 'package';
+        readonly description: 'A directory with a package manifest: an app, a library or a workspace.';
+    };
+    readonly file: {
+        readonly label: 'file';
+        readonly description: 'A file: source code, markdown, JSON, TOML, YAML, a skill, a schema, SQL and the rest.';
+    };
+    readonly namespace: {
+        readonly label: 'namespace';
+        readonly description: 'A namespace or a module.';
+    };
+    readonly class: {
+        readonly label: 'class';
+        readonly description: 'A class.';
+    };
+    readonly interface: {
+        readonly label: 'interface';
+        readonly description: 'An interface or a protocol.';
+    };
+    readonly struct: {
+        readonly label: 'struct';
+        readonly description: 'A struct or a record.';
+    };
+    readonly enum: {
+        readonly label: 'enum';
+        readonly description: 'An enumeration.';
+    };
+    readonly trait: {
+        readonly label: 'trait';
+        readonly description: 'A trait or a mixin.';
+    };
+    readonly type: {
+        readonly label: 'type';
+        readonly description: 'A type alias.';
+    };
+    readonly function: {
+        readonly label: 'function';
+        readonly description: 'A function or a method.';
+    };
+    readonly term: {
+        readonly label: 'term';
+        readonly description: 'A word of the project and what it means.';
+    };
+    readonly decision: {
+        readonly label: 'decision';
+        readonly description: 'A choice that is costly to undo, with its reason.';
+    };
+    readonly table: {
+        readonly label: 'table';
+        readonly description: 'A table of a SQL schema.';
+    };
+    readonly query: {
+        readonly label: 'query';
+        readonly description: 'An entry of a SQL query catalog.';
+    };
+    readonly plan: {
+        readonly label: 'plan';
+        readonly description: 'A plan of the task tree.';
+    };
+    readonly phase: {
+        readonly label: 'phase';
+        readonly description: 'A phase of a plan.';
+    };
+    readonly task: {
+        readonly label: 'task';
+        readonly description: 'One unit of work of a phase, with its status.';
+    };
+    readonly operation: {
+        readonly label: 'operation';
+        readonly description: 'A method on a path of an API. Found by search, which returns its file.';
+        readonly member: true;
+    };
+    readonly definition: {
+        readonly label: 'definition';
+        readonly description: 'A named JSON Schema. Found by search, which returns its file.';
+        readonly member: true;
+    };
+    readonly parameter: {
+        readonly label: 'parameter';
+        readonly description: 'A parameter of a function, an operation or a query. Found by search, which returns its owner.';
+        readonly member: true;
+    };
+    readonly field: {
+        readonly label: 'field';
+        readonly description: 'A field of a type, a property, a column or a result column. Found by search, which returns its owner.';
+        readonly member: true;
+    };
+};
+/**
+ * Every node type, in the order the site lists them. A node type decides how the scanner reads a node and how
+ * its page renders; `kind` names the node kind it belongs to, which is what queries, filters and the graph use.
+ */
+export declare const NODE_TYPE_REGISTRY: {
     readonly section: {
+        readonly kind: 'folder';
         readonly group: 'section';
         readonly label: 'section';
         readonly description: 'A top-level group of the site.';
     };
     readonly folder: {
+        readonly kind: 'folder';
         readonly group: 'folder';
         readonly label: 'folder';
         readonly description: 'A directory of the repository.';
     };
+    readonly package: {
+        readonly kind: 'package';
+        readonly group: 'folder';
+        readonly label: 'package';
+        readonly description: 'A directory with a package manifest: an app, a library or a workspace.';
+    };
     readonly skill: {
+        readonly kind: 'file';
         readonly group: 'file';
         readonly label: 'skill';
         readonly description: 'A `SKILL.md`. The other files of its directory belong to it.';
     };
     readonly reference: {
+        readonly kind: 'file';
         readonly group: 'file';
         readonly label: 'reference';
         readonly description: 'A markdown file of a skill.';
     };
     readonly agent: {
+        readonly kind: 'file';
         readonly group: 'file';
         readonly label: 'agent';
         readonly description: 'A file in the `agents/` directory of a skill.';
     };
     readonly hook: {
+        readonly kind: 'file';
         readonly group: 'file';
         readonly label: 'hook';
         readonly description: 'A file in the `hooks/` directory of a skill.';
     };
     readonly schema: {
+        readonly kind: 'file';
         readonly group: 'file';
         readonly label: 'schema';
         readonly description: 'A JSON Schema, or a schema file of a skill.';
     };
     readonly asset: {
+        readonly kind: 'file';
         readonly group: 'file';
         readonly label: 'file';
         readonly description: 'Any other file of a skill.';
     };
     readonly document: {
+        readonly kind: 'file';
         readonly group: 'file';
         readonly label: 'document';
         readonly description: 'A markdown file.';
     };
     readonly json: {
+        readonly kind: 'file';
         readonly group: 'file';
         readonly label: 'JSON';
         readonly description: 'A JSON file.';
     };
+    readonly toml: {
+        readonly kind: 'file';
+        readonly group: 'file';
+        readonly label: 'TOML';
+        readonly description: 'A TOML file.';
+    };
+    readonly yaml: {
+        readonly kind: 'file';
+        readonly group: 'file';
+        readonly label: 'YAML';
+        readonly description: 'A YAML file.';
+    };
     readonly glossary: {
+        readonly kind: 'file';
         readonly group: 'file';
         readonly label: 'glossary';
         readonly description: 'A `glossary.md`. Its terms are its entries.';
     };
     readonly decisions: {
+        readonly kind: 'file';
         readonly group: 'file';
         readonly label: 'decisions';
         readonly description: 'A `decisions.md`. Its decisions are its entries.';
     };
     readonly api: {
+        readonly kind: 'file';
         readonly group: 'file';
         readonly label: 'API';
         readonly description: 'An OpenAPI document. Its operations and definitions are its entries.';
     };
     readonly database: {
+        readonly kind: 'file';
         readonly group: 'file';
         readonly label: 'database';
         readonly description: 'A `.sql` file that creates tables. Its tables are its entries.';
     };
     readonly catalog: {
+        readonly kind: 'file';
         readonly group: 'file';
         readonly label: 'catalog';
         readonly description: 'A directory of `.sql` files that create no table. Its queries are its entries.';
     };
     readonly plan: {
+        readonly kind: 'plan';
         readonly group: 'file';
         readonly label: 'plan';
         readonly description: 'A plan of the task tree. Its phases are its children.';
     };
     readonly phase: {
+        readonly kind: 'phase';
         readonly group: 'file';
         readonly label: 'phase';
         readonly description: 'A phase of a plan. Its tasks are its entries.';
     };
     readonly source: {
+        readonly kind: 'file';
         readonly group: 'source';
         readonly label: 'code';
         readonly description: 'A source file. Its classes and functions are its entries.';
     };
     readonly namespace: {
+        readonly kind: 'namespace';
         readonly group: 'symbol';
         readonly label: 'namespace';
         readonly description: 'A namespace or a module.';
@@ -192,6 +337,7 @@ export declare const NODE_KIND_REGISTRY: {
         readonly container: true;
     };
     readonly class: {
+        readonly kind: 'class';
         readonly group: 'symbol';
         readonly label: 'class';
         readonly description: 'A class.';
@@ -200,6 +346,7 @@ export declare const NODE_KIND_REGISTRY: {
         readonly container: true;
     };
     readonly interface: {
+        readonly kind: 'interface';
         readonly group: 'symbol';
         readonly label: 'interface';
         readonly description: 'An interface or a protocol.';
@@ -208,6 +355,7 @@ export declare const NODE_KIND_REGISTRY: {
         readonly container: true;
     };
     readonly struct: {
+        readonly kind: 'struct';
         readonly group: 'symbol';
         readonly label: 'struct';
         readonly description: 'A struct or a record.';
@@ -216,6 +364,7 @@ export declare const NODE_KIND_REGISTRY: {
         readonly container: true;
     };
     readonly enum: {
+        readonly kind: 'enum';
         readonly group: 'symbol';
         readonly label: 'enum';
         readonly description: 'An enumeration.';
@@ -224,6 +373,7 @@ export declare const NODE_KIND_REGISTRY: {
         readonly container: true;
     };
     readonly trait: {
+        readonly kind: 'trait';
         readonly group: 'symbol';
         readonly label: 'trait';
         readonly description: 'A trait or a mixin.';
@@ -232,6 +382,7 @@ export declare const NODE_KIND_REGISTRY: {
         readonly container: true;
     };
     readonly type: {
+        readonly kind: 'type';
         readonly group: 'symbol';
         readonly label: 'type';
         readonly description: 'A type alias.';
@@ -240,65 +391,76 @@ export declare const NODE_KIND_REGISTRY: {
         readonly container: true;
     };
     readonly function: {
+        readonly kind: 'function';
         readonly group: 'symbol';
         readonly label: 'function';
         readonly description: 'A function.';
         readonly letter: 'F';
     };
     readonly method: {
+        readonly kind: 'function';
         readonly group: 'symbol';
         readonly label: 'method';
         readonly description: 'A method of a type.';
         readonly letter: 'M';
     };
     readonly term: {
+        readonly kind: 'term';
         readonly group: 'entry';
         readonly label: 'term';
         readonly description: 'A word of the project and what it means.';
         readonly prose: true;
     };
     readonly decision: {
+        readonly kind: 'decision';
         readonly group: 'entry';
         readonly label: 'decision';
         readonly description: 'A choice that is costly to undo, with its reason.';
         readonly prose: true;
     };
     readonly operation: {
+        readonly kind: 'operation';
         readonly group: 'entry';
         readonly label: 'operation';
         readonly description: 'A method on a path of an API.';
         readonly described: true;
     };
     readonly definition: {
+        readonly kind: 'definition';
         readonly group: 'entry';
         readonly label: 'definition';
         readonly description: 'A named JSON Schema.';
         readonly described: true;
     };
     readonly table: {
+        readonly kind: 'table';
         readonly group: 'entry';
         readonly label: 'table';
         readonly description: 'A table of a SQL schema.';
         readonly described: true;
     };
     readonly query: {
+        readonly kind: 'query';
         readonly group: 'entry';
         readonly label: 'query';
         readonly description: 'An entry of a SQL query catalog.';
         readonly described: true;
     };
     readonly task: {
+        readonly kind: 'task';
         readonly group: 'entry';
         readonly label: 'task';
         readonly description: 'One unit of work of a phase, with its status.';
         readonly prose: true;
     };
     readonly parameter: {
+        readonly kind: 'parameter';
         readonly group: 'member';
         readonly label: 'parameter';
         readonly description: 'A parameter of a function, an operation or a query.';
     };
     readonly field: {
+        readonly kind: 'field';
         readonly group: 'member';
         readonly label: 'field';
         readonly description: 'A field of a type, a property, a column or a result column.';
@@ -460,7 +622,9 @@ export declare const RELATION_KIND_REGISTRY: {
 };
 /** Slug of a top-level section, such as `code`. */
 export type Section = keyof typeof SECTION_REGISTRY;
-/** Kind of a node, such as `class` or `table`. */
+/** Type of a node, such as `method`, `api` or `table`. Decides how the scanner reads it and how its page renders. */
+export type NodeType = keyof typeof NODE_TYPE_REGISTRY;
+/** Kind of a node, such as `function`, `file` or `table`. What queries, filters and the graph use. */
 export type NodeKind = keyof typeof NODE_KIND_REGISTRY;
 /** Name of a relation family, such as `typing`. */
 export type RelationFamily = keyof typeof RELATION_FAMILY_REGISTRY;
@@ -468,8 +632,12 @@ export type RelationFamily = keyof typeof RELATION_FAMILY_REGISTRY;
 export type EdgeKind = keyof typeof RELATION_KIND_REGISTRY;
 /** The node kinds whose group is one of `G`. */
 export type KindsIn<G extends NodeGroup> = {
-    [K in NodeKind]: (typeof NODE_KIND_REGISTRY)[K]['group'] extends G ? K : never;
-}[NodeKind];
+    [K in NodeType]: (typeof NODE_TYPE_REGISTRY)[K]['group'] extends G ? K : never;
+}[NodeType];
+/** Every node kind with its parsed spec. */
+export declare const NODE_TYPES: Readonly<Record<NodeType, NodeTypeSpec & {
+    kind: NodeKind;
+}>>;
 /** Every node kind with its parsed spec. */
 export declare const NODE_KINDS: Readonly<Record<NodeKind, NodeKindSpec>>;
 /** Every section with its parsed spec. */
@@ -482,13 +650,38 @@ export declare const RELATION_KINDS: Readonly<Record<EdgeKind, RelationKindSpec
 }>>;
 /** The sections, in display order. */
 export declare const SECTIONS: readonly Section[];
+/** Every node type, in registry order. */
+export declare const ALL_NODE_TYPES: readonly NodeType[];
 /** Every node kind, in registry order. */
 export declare const ALL_NODE_KINDS: readonly NodeKind[];
+/**
+ * @brief Names the node kind a node type belongs to.
+ *
+ * @param type - Type of a node, such as `method`.
+ * @returns Its kind, such as `function`.
+ */
+export declare function kindOf(type: NodeType): NodeKind;
+/**
+ * @brief Tells whether a node kind is a member kind: found by search and filters, which return the node it belongs to.
+ *
+ * @param kind - Kind of a node, such as `field`.
+ */
+export declare function isMemberKind(kind: NodeKind): boolean;
 /** Every relation kind, in registry order. */
 export declare const EDGE_KINDS: readonly EdgeKind[];
 /** Every relation family, in legend order. */
 export declare const RELATION_FAMILY_NAMES: readonly RelationFamily[];
-/** Lists the node kinds whose group is one of `groups`, in registry order. */
+/**
+ * Lists the node kinds whose group is one of `groups`, in registry order.
+ *
+ * @param groups - Groups to keep, such as `symbol` or `entry`.
+ * @returns The kinds of those groups.
+ */
 export declare function kindsIn<G extends NodeGroup>(...groups: readonly G[]): readonly KindsIn<G>[];
-/** Lists the node kinds for which a flag of the registry is set. */
-export declare function kindsWith(flag: 'typeLike' | 'container' | 'described'): ReadonlySet<NodeKind>;
+/**
+ * Lists the node kinds for which a flag of the registry is set.
+ *
+ * @param flag - Flag of the node kind spec to test.
+ * @returns The kinds whose flag is set.
+ */
+export declare function kindsWith(flag: 'typeLike' | 'container' | 'described'): ReadonlySet<NodeType>;

package/dist/query/graph.d.ts

@@ -1,8 +1,12 @@
-import { type BundleMeta, type DocsBundle, type Edge, type GraphNode, type NodeKind, type NodeRef, type Route, type Section, type SemanticIndex } from '../model';
-/** Tells whether a kind is a row of its entry (`parameter` or `field`) rather than a page or entry of its own. */
-export declare function isDeclarationKind(kind: NodeKind): kind is 'parameter' | 'field';
+import { type BundleMeta, type DocsBundle, type Edge, type GraphNode, type NodeType, type NodeRef, type Route, type Section, type SemanticIndex } from '../model';
 /**
- * The bundle as a graph the app can walk: children, routes and edges in both
+ * Tells whether a kind is a row of its entry (`parameter` or `field`) rather than a page or entry of its own.
+ *
+ * @param kind - Kind of a node, such as `parameter`.
+ */
+export declare function isDeclarationKind(kind: NodeType): kind is 'parameter' | 'field';
+/**
+ * @brief The bundle as a graph the app can walk: children, routes and edges in both
  * directions. Built once at startup.
  *
  * Holds the bundle's nodes and meta, the semantic index, and lookup tables
@@ -10,57 +14,110 @@ export declare function isDeclarationKind(kind: NodeKind): kind is 'parameter' |
  * entries by `path#hash`, and edges by source and by target. `web/main.tsx`
  * creates it from the embedded bundle and `api/source.ts` from a loaded one.
  * The web app, `retrieval/` and the search functions in `query/` read it.
+ *
+ * Create one with `new Graph(bundle)`.
+ *
+ * @property meta - Title, generation time and generator of the bundle.
+ * @property semantic - The embedding model and node vectors for search by meaning, when the bundle has them.
+ * @property sections - The sections of the bundle, in display order. Some bundles lack `database`, so a walk over every section goes through this list.
  */
 export declare class Graph {
     readonly meta: BundleMeta;
-    /** The embedding model and node vectors for search by meaning, when the page has them. */
     readonly semantic: SemanticIndex | undefined;
     private readonly nodes;
     private readonly childRefs;
     private readonly routes;
-    /** Route path to the page it shows. */
     private readonly pages;
-    /** `path#hash` to the entry it names: a symbol, a term or a decision. */
     private readonly anchors;
     private readonly outgoing;
     private readonly incoming;
-    /**
-     * The sections of the bundle, in display order. A bundle that an older
-     * version wrote has no `database` section, so a walk over every section
-     * goes through this list.
-     */
     readonly sections: readonly {
         readonly slug: Section;
         readonly node: NodeRef;
     }[];
-    /** Indexes the nodes and edges of a bundle. */
+    /**
+     * Indexes the nodes and edges of a bundle.
+     *
+     * @param bundle - Bundle to index, from the embedded data or a loaded file.
+     */
     constructor(bundle: DocsBundle);
-    /** Returns the node at `ref`, and throws when there is none. */
+    /**
+     * Returns the node at `ref`, and throws when there is none.
+     *
+     * @param ref - Index of the node in the bundle.
+     */
     node(ref: NodeRef): GraphNode;
-    /** Returns the children of a node in display order. */
+    /**
+     * Returns the children of a node in display order.
+     *
+     * @param ref - Index of the parent node.
+     */
     children(ref: NodeRef): readonly NodeRef[];
-    /** From the section down to the parent of `ref`. */
+    /**
+     * From the section down to the parent of `ref`.
+     *
+     * @param ref - Index of the node.
+     */
     ancestors(ref: NodeRef): NodeRef[];
-    /** Returns the route of the page that shows a node, and throws when there is no node at `ref`. */
+    /**
+     * Returns the route of the page that shows a node, and throws when there is no node at `ref`.
+     *
+     * @param ref - Index of the node.
+     * @returns The route of the page, with the hash of the entry when the node is one.
+     */
     route(ref: NodeRef): Route;
-    /** The node a location shows: the entry `hash` names on the page at `path`, else that page. */
+    /**
+     * The node a location shows: the entry `hash` names on the page at `path`, else that page.
+     *
+     * @param path - Page path, with or without leading and trailing slashes, such as `code/src/app.ts`.
+     * @param hash - Anchor of an entry on that page, such as `symbol:App.run`, without `#`.
+     * @returns The node, or `undefined` when the location names none.
+     */
     at(path: string, hash?: string): NodeRef | undefined;
-    /** Returns the root node of a section, and throws when the bundle lacks it. */
+    /**
+     * Returns the root node of a section, and throws when the bundle lacks it.
+     *
+     * @param slug - Section slug, such as `code`.
+     */
     section(slug: Section): NodeRef;
-    /** The section a node is in. */
+    /**
+     * The section a node is in.
+     *
+     * @param ref - Index of the node.
+     * @returns Index of the section node, or `ref` itself when it is a section.
+     */
     sectionOf(ref: NodeRef): NodeRef;
-    /** Every node below `ref`, depth first, in display order. */
+    /**
+     * Every node below `ref`, depth first, in display order.
+     *
+     * @param ref - Index of the node whose descendants are listed.
+     */
     descendants(ref: NodeRef): Generator<NodeRef>;
-    /** Number of nodes below `ref` whose kind is one of `kinds`. */
-    count(ref: NodeRef, kinds: ReadonlySet<NodeKind>): number;
-    /** Returns the edges that start at a node. */
+    /**
+     * Number of nodes below `ref` whose kind is one of `kinds`.
+     *
+     * @param ref - Index of the node whose descendants are counted.
+     * @param kinds - Kinds to count, such as `table` or `field`.
+     */
+    count(ref: NodeRef, kinds: ReadonlySet<NodeType>): number;
+    /**
+     * Returns the edges that start at a node.
+     *
+     * @param ref - Index of the source node.
+     */
     edgesFrom(ref: NodeRef): readonly Edge[];
-    /** Returns the edges that end at a node. */
+    /**
+     * Returns the edges that end at a node.
+     *
+     * @param ref - Index of the target node.
+     */
     edgesTo(ref: NodeRef): readonly Edge[];
     /**
-     * Name of a node as other places refer to it: `Class.method` for a symbol,
+     * @brief Name of a node as other places refer to it: `Class.method` for a symbol,
      * `Class.method(parameter)` for a parameter, `table.column` for a column,
      * `query(:placeholder)` for a placeholder of a query, the file path for a page.
+     *
+     * @param ref - Index of the node.
      */
     qualifiedName(ref: NodeRef): string;
 }