@g3nomaly/analyze 0.0.0-stage → 0.1.1

package/dist/model/registry.d.ts

@@ -0,0 +1,687 @@
+import * as z from 'zod/mini';
+/**
+ * The role a node kind plays in the site.
+ * - `section`: a top-level group.
+ * - `folder`: a directory.
+ * - `file`: a file with a page of its own.
+ * - `source`: a source file, a page whose symbols are its entries.
+ * - `symbol`: a declaration in code, shown as an entry.
+ * - `entry`: any other block on the page of its file, with an anchor of its own.
+ * - `member`: a parameter or a field, a row of its entry.
+ */
+export declare const NodeGroupSchema: z.ZodMiniEnum<{
+    entry: "entry";
+    file: "file";
+    folder: "folder";
+    member: "member";
+    section: "section";
+    source: "source";
+    symbol: "symbol";
+}>;
+/** One of the roles of {@link NodeGroupSchema}. */
+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";
+        folder: "folder";
+        member: "member";
+        section: "section";
+        source: "source";
+        symbol: "symbol";
+    }>;
+    label: z.ZodMiniString<string>;
+    description: z.ZodMiniString<string>;
+    letter: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    prose: z.ZodMiniDefault<z.ZodMiniBoolean<boolean>>;
+    typeLike: z.ZodMiniDefault<z.ZodMiniBoolean<boolean>>;
+    container: z.ZodMiniDefault<z.ZodMiniBoolean<boolean>>;
+    described: z.ZodMiniDefault<z.ZodMiniBoolean<boolean>>;
+}, z.core.$strict>;
+/** The parsed spec of one node kind, with defaults filled in. */
+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>;
+    description: z.ZodMiniString<string>;
+}, z.core.$strict>;
+/** The parsed spec of one section. */
+export type SectionSpec = z.infer<typeof SectionSpecSchema>;
+/** What the registry states about a family of relation kinds that the graph draws in one color. */
+export declare const RelationFamilySpecSchema: z.ZodMiniObject<{
+    label: z.ZodMiniString<string>;
+    description: z.ZodMiniString<string>;
+    colorToken: z.ZodMiniString<string>;
+}, z.core.$strict>;
+/** The parsed spec of one relation family. */
+export type RelationFamilySpec = z.infer<typeof RelationFamilySpecSchema>;
+/** What the registry states about one relation kind: what it means, which way it points and how it is drawn. */
+export declare const RelationKindSpecSchema: z.ZodMiniObject<{
+    label: z.ZodMiniString<string>;
+    description: z.ZodMiniString<string>;
+    forward: z.ZodMiniString<string>;
+    backward: z.ZodMiniString<string>;
+    from: z.ZodMiniString<string>;
+    to: z.ZodMiniString<string>;
+    family: z.ZodMiniString<string>;
+    dashed: z.ZodMiniDefault<z.ZodMiniBoolean<boolean>>;
+}, z.core.$strict>;
+/** The parsed spec of one relation kind, with defaults filled in. */
+export type RelationKindSpec = z.infer<typeof RelationKindSpecSchema>;
+/** The top-level sections, in display order. */
+export declare const SECTION_REGISTRY: {
+    readonly skills: {
+        readonly label: 'Skills';
+        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 files.';
+    };
+    readonly code: {
+        readonly label: 'Code';
+        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';
+        readonly description: 'SQL files, as schemas with their tables and as query catalogs.';
+    };
+    readonly tasks: {
+        readonly label: 'Tasks';
+        readonly description: 'Plans, their phases and their tasks, as task-manager keeps them.';
+    };
+};
+/**
+ * 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.';
+        readonly letter: 'N';
+        readonly container: true;
+    };
+    readonly class: {
+        readonly kind: 'class';
+        readonly group: 'symbol';
+        readonly label: 'class';
+        readonly description: 'A class.';
+        readonly letter: 'C';
+        readonly typeLike: true;
+        readonly container: true;
+    };
+    readonly interface: {
+        readonly kind: 'interface';
+        readonly group: 'symbol';
+        readonly label: 'interface';
+        readonly description: 'An interface or a protocol.';
+        readonly letter: 'I';
+        readonly typeLike: true;
+        readonly container: true;
+    };
+    readonly struct: {
+        readonly kind: 'struct';
+        readonly group: 'symbol';
+        readonly label: 'struct';
+        readonly description: 'A struct or a record.';
+        readonly letter: 'S';
+        readonly typeLike: true;
+        readonly container: true;
+    };
+    readonly enum: {
+        readonly kind: 'enum';
+        readonly group: 'symbol';
+        readonly label: 'enum';
+        readonly description: 'An enumeration.';
+        readonly letter: 'E';
+        readonly typeLike: true;
+        readonly container: true;
+    };
+    readonly trait: {
+        readonly kind: 'trait';
+        readonly group: 'symbol';
+        readonly label: 'trait';
+        readonly description: 'A trait or a mixin.';
+        readonly letter: 'T';
+        readonly typeLike: true;
+        readonly container: true;
+    };
+    readonly type: {
+        readonly kind: 'type';
+        readonly group: 'symbol';
+        readonly label: 'type';
+        readonly description: 'A type alias.';
+        readonly letter: 'T';
+        readonly typeLike: true;
+        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.';
+    };
+};
+/** The relation families, in legend order. */
+export declare const RELATION_FAMILY_REGISTRY: {
+    readonly typing: {
+        readonly label: 'typing';
+        readonly description: 'What a declaration is made of.';
+        readonly colorToken: '--edge-typing';
+    };
+    readonly result: {
+        readonly label: 'result';
+        readonly description: 'What a call gives back.';
+        readonly colorToken: '--edge-result';
+    };
+    readonly prose: {
+        readonly label: 'prose';
+        readonly description: 'What a text points at.';
+        readonly colorToken: '--edge-prose';
+    };
+    readonly term: {
+        readonly label: 'term';
+        readonly description: 'A text that uses a glossary term.';
+        readonly colorToken: '--edge-term';
+    };
+    readonly key: {
+        readonly label: 'key';
+        readonly description: 'A foreign key between two tables.';
+        readonly colorToken: '--edge-key';
+    };
+    readonly query: {
+        readonly label: 'query';
+        readonly description: 'A table a query reads or writes.';
+        readonly colorToken: '--edge-query';
+    };
+    readonly task: {
+        readonly label: 'task';
+        readonly description: 'What a task names, and what it waits for.';
+        readonly colorToken: '--edge-task';
+    };
+};
+/** Every relation kind other than `parent`, in the order the site lists them. */
+export declare const RELATION_KIND_REGISTRY: {
+    readonly type: {
+        readonly label: 'type';
+        readonly description: 'A parameter or field has that type, or the request body of an operation has that schema.';
+        readonly forward: 'has type';
+        readonly backward: 'is the type of';
+        readonly from: 'parameter, field, property or operation';
+        readonly to: 'type or definition';
+        readonly family: 'typing';
+    };
+    readonly returns: {
+        readonly label: 'returns';
+        readonly description: 'A function returns that type, or an operation answers with that schema.';
+        readonly forward: 'returns';
+        readonly backward: 'is returned by';
+        readonly from: 'function, method or operation';
+        readonly to: 'type or definition';
+        readonly family: 'result';
+    };
+    readonly throws: {
+        readonly label: 'throws';
+        readonly description: 'A function throws that type, or an operation answers an error with that schema.';
+        readonly forward: 'throws';
+        readonly backward: 'is thrown by';
+        readonly from: 'function, method or operation';
+        readonly to: 'type or definition';
+        readonly family: 'result';
+        readonly dashed: true;
+    };
+    readonly extends: {
+        readonly label: 'extends';
+        readonly description: 'A type extends, implements or is composed of that type.';
+        readonly forward: 'extends';
+        readonly backward: 'is extended by';
+        readonly from: 'type or definition';
+        readonly to: 'type or definition';
+        readonly family: 'typing';
+        readonly dashed: true;
+    };
+    readonly mentions: {
+        readonly label: 'mentions';
+        readonly description: 'A page or a description links to that node.';
+        readonly forward: 'mentions';
+        readonly backward: 'is mentioned by';
+        readonly from: 'page or entry';
+        readonly to: 'any node';
+        readonly family: 'prose';
+    };
+    readonly uses: {
+        readonly label: 'uses';
+        readonly description: 'A page, a description or a decision uses that glossary term.';
+        readonly forward: 'uses';
+        readonly backward: 'is used by';
+        readonly from: 'page, entry, parameter or field';
+        readonly to: 'term';
+        readonly family: 'term';
+    };
+    readonly affects: {
+        readonly label: 'affects';
+        readonly description: 'A decision is about that node.';
+        readonly forward: 'affects';
+        readonly backward: 'is affected by';
+        readonly from: 'decision';
+        readonly to: 'any node';
+        readonly family: 'prose';
+        readonly dashed: true;
+    };
+    readonly references: {
+        readonly label: 'references';
+        readonly description: 'A table has a foreign key to that table.';
+        readonly forward: 'references';
+        readonly backward: 'is referenced by';
+        readonly from: 'table';
+        readonly to: 'table';
+        readonly family: 'key';
+    };
+    readonly reads: {
+        readonly label: 'reads';
+        readonly description: 'A query selects from that table.';
+        readonly forward: 'reads';
+        readonly backward: 'is read by';
+        readonly from: 'query';
+        readonly to: 'table';
+        readonly family: 'query';
+    };
+    readonly writes: {
+        readonly label: 'writes';
+        readonly description: 'A statement inserts into, updates or deletes from that table.';
+        readonly forward: 'writes';
+        readonly backward: 'is written by';
+        readonly from: 'query';
+        readonly to: 'table';
+        readonly family: 'query';
+        readonly dashed: true;
+    };
+    readonly names: {
+        readonly label: 'names';
+        readonly description: 'A plan, a phase or a task links to that node or names it in inline code.';
+        readonly forward: 'names';
+        readonly backward: 'is named by';
+        readonly from: 'plan, phase or task';
+        readonly to: 'any node';
+        readonly family: 'task';
+    };
+    readonly depends: {
+        readonly label: 'depends';
+        readonly description: 'A plan, a phase or a task waits for that one to be completed.';
+        readonly forward: 'depends on';
+        readonly backward: 'is depended on by';
+        readonly from: 'plan, phase or task';
+        readonly to: 'plan, phase or task';
+        readonly family: 'task';
+        readonly dashed: true;
+    };
+};
+/** Slug of a top-level section, such as `code`. */
+export type Section = keyof typeof SECTION_REGISTRY;
+/** 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;
+/** Kind of an edge: any relation kind other than `parent`. */
+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 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. */
+export declare const SECTION_SPECS: Readonly<Record<Section, SectionSpec>>;
+/** Every relation family with its parsed spec. */
+export declare const RELATION_FAMILIES: Readonly<Record<RelationFamily, RelationFamilySpec>>;
+/** Every relation kind with its parsed spec. */
+export declare const RELATION_KINDS: Readonly<Record<EdgeKind, RelationKindSpec & {
+    family: RelationFamily;
+}>>;
+/** 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.
+ *
+ * @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.
+ *
+ * @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>;