@g3nomaly/analyze 0.1.4 → 0.1.6

package/dist/scanner/code/extract.d.ts

@@ -1,6 +1,7 @@
 import { type SymbolKind } from '../../model';
 import type { Node, Query } from 'web-tree-sitter';
-import { type RawCall } from './calls';
+import { type BodyReferences } from './calls';
+import { type FileExports } from './exports';
 import type { ImportRequest } from './imports';
 import type { LanguageSpec } from './language';
 /**
@@ -41,6 +42,8 @@ export interface RawField {
  * @brief One definition as found in the syntax tree, before rendering.
  *
  * @property kind - Kind of the symbol, such as `function`, `method`, `class` or `enum`.
+ * @property line - Line of the file where the declaration starts.
+ * @property endLine - Line of the file where the declaration ends.
  * @property signature - Declaration head. Empty when `inferred`.
  * @property modifiers - Keywords in front of the name, such as `export` or `static`.
  * @property comment - Cleaned doc comment text, or `null`.
@@ -54,13 +57,16 @@ export interface RawField {
  * @property returnsValue - True when a call to the symbol yields a value.
  * @property inferred - True for an owner type that is not declared in this file.
  * @property internal - True for a function only its own file can call, as the spec's `isInternal` decides.
+ * @property accessor - True for a getter or a setter, such as `get size()` or a Python `@property`. Reading it runs it.
  * @property calls - For a function or method: the calls in its body, each once.
+ * @property passes - For a function or method: the names its body passes on as values, each once.
  * @property children - Members nested under this symbol.
  */
-export interface RawSymbol {
+export interface RawSymbol extends BodyReferences {
     kind: SymbolKind;
     readonly name: string;
     readonly line: number;
+    readonly endLine: number;
     readonly signature: string;
     readonly modifiers: readonly string[];
     readonly annotations: readonly string[];
@@ -76,7 +82,7 @@ export interface RawSymbol {
     returnsValue: boolean;
     readonly inferred: boolean;
     readonly internal: boolean;
-    readonly calls: readonly RawCall[];
+    readonly accessor: boolean;
     readonly children: RawSymbol[];
 }
 /**
@@ -85,11 +91,13 @@ export interface RawSymbol {
  * @property symbols - Top-level symbols of the file, each with its members nested under it.
  * @property packageName - Package or namespace the file declares, or `null` when the language has none.
  * @property imports - The files the file imports, as it writes them. Empty for a language without `imports`.
+ * @property exports - The names the file exports. Empty for a language whose imports do not read exports.
  */
 export interface ExtractedFile {
     readonly symbols: RawSymbol[];
     readonly packageName: string | null;
     readonly imports: readonly ImportRequest[];
+    readonly exports: FileExports;
 }
 /**
  * @brief Turns a parsed file into a tree of {@link RawSymbol}s, driven by a {@link LanguageSpec}.

package/dist/scanner/code/imports.d.ts

@@ -1,5 +1,6 @@
 import type { Node } from 'web-tree-sitter';
 import type { NodeRef } from '../../model';
+import { type FileExports } from './exports';
 /**
  * @brief One import of a file: the paths it can stand for, most specific first. The first one that names a
  * file of the scan wins.
@@ -21,6 +22,13 @@ export interface ImportSyntax {
      * @returns One request per import, as the file writes it.
      */
     read(root: Node): ImportRequest[];
+    /**
+     * @brief Reads the names a parsed file exports, for a language whose packages export names from an entry file.
+     *
+     * @param root - Root node of the parsed file.
+     * @returns The names it declares and exports, and the files it re-exports from.
+     */
+    readExports?(root: Node): FileExports;
     /**
      * @brief Finds the file an import names.
      *
@@ -43,6 +51,7 @@ export interface ImportSyntax {
  * @property entries - Each file by display path.
  * @property byName - Display paths of the files with each file name.
  * @property packages - Directory of each package of the scan, by the name its manifest gives.
+ * @property entryPoints - The subpaths each package is imported by, by the name its manifest gives.
  * @property resolved - Display paths each file imports, resolved on first use.
  * @property seen - Display paths each file sees, computed on first use.
  */
@@ -50,6 +59,7 @@ export declare class SourceFileIndex {
     private readonly entries;
     private readonly byName;
     private packages;
+    private entryPoints;
     private readonly resolved;
     private readonly seen;
     /**
@@ -59,8 +69,9 @@ export declare class SourceFileIndex {
      * @param ref - Node of the file.
      * @param syntax - How its language names imports, or `null` when its imports are not read.
      * @param requests - Its imports, as the file writes them.
+     * @param exports - The names it exports, from `readExports` of its language.
      */
-    add(path: string, ref: NodeRef, syntax: ImportSyntax | null, requests: readonly ImportRequest[]): void;
+    add(path: string, ref: NodeRef, syntax: ImportSyntax | null, requests: readonly ImportRequest[], exports: FileExports): void;
     /**
      * @brief Tells the index where each package of the scan is, so an import of a package by name finds its files.
      *
@@ -68,7 +79,15 @@ export declare class SourceFileIndex {
      */
     usePackages(packages: ReadonlyMap<string, {
         readonly packageName: string;
+        readonly entryPoints: readonly string[];
     }>): void;
+    /**
+     * @brief The subpaths a package is imported by.
+     *
+     * @param name - Name its manifest gives, such as `@g3nomaly/core`.
+     * @returns `''` for the name itself, then subpaths such as `hash`. `['']` for a package the scan does not have.
+     */
+    entryPointsOf(name: string): readonly string[];
     /**
      * @brief Directory of the package with a name.
      *
@@ -76,6 +95,28 @@ export declare class SourceFileIndex {
      * @returns Display path of its directory, `''` for the root, or `undefined` when the scan has no such package.
      */
     packageDirectory(name: string): string | undefined;
+    /**
+     * @brief Names the package a file is in: the package of the scan whose directory holds it most closely.
+     *
+     * @param path - Display path of a file.
+     * @returns The name its manifest gives, such as `@g3nomaly/core`, or `null` when no package holds the file.
+     */
+    packageOf(path: string): string | null;
+    /**
+     * @brief Finds the file one import of a file names, with the import syntax of that file's language.
+     *
+     * @param specifier - The import as written, such as `./hash` or `@g3nomaly/core`.
+     * @param from - Display path of the importing file.
+     * @returns Display path of the file, or `null` when the scan has none or the file's imports are not read.
+     */
+    resolveImport(specifier: string, from: string): string | null;
+    /**
+     * @brief The names a file exports.
+     *
+     * @param path - Display path of a file.
+     * @returns Its exports, empty for a file the scan does not have.
+     */
+    exportsOf(path: string): FileExports;
     /**
      * @brief Node of the source file at `path`.
      *

package/dist/scanner/code/language.d.ts

@@ -1,5 +1,6 @@
 import type { SymbolKind } from '../../model';
 import type { Node } from 'web-tree-sitter';
+import type { PackageImport } from './exports';
 import type { ImportSyntax } from './imports';
 /**
  * @brief Doc comment dialect, which decides how the scanner reads doc comments.
@@ -35,6 +36,8 @@ export interface DefinitionFacts {
  * @property kind - Kind of that outermost symbol.
  * @property modifiers - Keywords in front of the name, such as `export` or `default`.
  * @property packageName - Package or namespace the file declares with a statement, e.g. `a.b` for Java's `package a.b;`, or `null`.
+ * @property packageImport - For a symbol the entry file of its package exports, the package name and the name it is
+ *   exported under, as code outside the package imports it. `null` when no package of the scan exports it.
  */
 export interface ImportContext {
     readonly filePath: string;
@@ -42,6 +45,7 @@ export interface ImportContext {
     readonly kind: SymbolKind;
     readonly modifiers: readonly string[];
     readonly packageName: string | null;
+    readonly packageImport: PackageImport | null;
 }
 /**
  * How a language spells a call. Drives generated examples.

package/dist/scanner/code/symbols.d.ts

@@ -88,8 +88,8 @@ export declare class SymbolPlanner {
      */
     private symbolContent;
     /**
-     * @brief Records the `calls` edges of a function, with its parameters and the fields of its type as the
-     * variables a call can go through.
+     * @brief Records the `calls` and `passes` edges of a function, with its parameters and the fields of its type as
+     * the variables a call can go through. A parameter passed on by name is a value, never a function of the scan.
      *
      * @param symbol - The calling function.
      * @param scope - Where the function sits in the file.

package/dist/scanner/files.d.ts

@@ -58,7 +58,9 @@ export declare class RepoFileLister implements FileLister {
      */
     private isExcluded;
     /**
-     * @brief Lists the tracked and untracked files git does not ignore.
+     * @brief Lists the tracked and untracked files git does not ignore, without symlinks and files whose real path
+     * leaves `root`. A path missing from disk stays in the list. Turns off `core.fsmonitor`, so the repository's
+     * config cannot make git run a command.
      *
      * @param root - Absolute directory.
      * @returns Root-relative paths, or `null` when `root` is not in a git work tree or git fails.

package/dist/scanner/graph/communities.d.ts

@@ -3,8 +3,9 @@ import type { CommunityIndex, Edge, GraphNode } from '../../model';
  * @brief Splits the nodes of a scan into communities: groups whose nodes link to each other more than to the rest.
  *
  * Every page and entry is one unit: a file, a class, a function, a term, a table. A parameter or field counts
- * as the entry it belongs to. A section, folder or package belongs to no community. Every edge between two
- * units links them, and so does each unit with the unit it is in, such as a method with its class.
+ * as the entry it belongs to. A section, folder or package belongs to no community, and nor does a unit that would
+ * be alone in one. Every edge between two units links them, and so does each unit with the unit it is in, such as a
+ * method with its class.
  *
  * The split maximises modularity with the Louvain method: nodes move to the community of a neighbour while
  * that raises modularity, then each community becomes one node and the next level starts. It walks the nodes

package/dist/scanner/index.d.ts

@@ -1,4 +1,4 @@
-export { CallLinker, type CallContext, type CallVia, type RawCall, readCalls } from './code/calls';
+export { type BodyReferences, CallLinker, type CallContext, type CallVia, type RawCall, readReferences } from './code/calls';
 export { type ExtractedFile, type RawField, type RawParameter, type RawSymbol, SymbolExtractor } from './code/extract';
 export { GrammarLoader } from './code/grammar';
 export { C_INCLUDES, ECMASCRIPT_IMPORTS, type ImportRequest, type ImportSyntax, PYTHON_IMPORTS, SourceFileIndex, } from './code/imports';

package/dist/scanner/packages.d.ts

@@ -8,6 +8,9 @@ import type { Source } from './files';
  * @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 `''`.
+ * @property entryPoints - The subpaths code outside the package imports it by, `''` for the package name itself,
+ *   such as `['', 'hash']` for `@g3nomaly/core` and `@g3nomaly/core/hash`. The `exports` of a `package.json` lists
+ *   them; any other manifest has `['']`.
  */
 export interface PackageInfo {
     readonly packageName: string;
@@ -15,6 +18,7 @@ export interface PackageInfo {
     readonly manifest: string;
     readonly version: string | null;
     readonly description: string;
+    readonly entryPoints: readonly string[];
 }
 /**
  * @brief Finds the packages of a set of sources: every directory below a root with a manifest that one of the readers understands.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@g3nomaly/analyze",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Turns a repository into one offline HTML documentation site, and queries the same linked model from the terminal and from hooks.",
   "keywords": [
     "documentation",
@@ -40,7 +40,7 @@
     "docs": "bun run build && bun dist/cli.js create_docs"
   },
   "dependencies": {
-    "@g3nomaly/core": "^0.3.5",
+    "@g3nomaly/core": "^0.3.7",
     "@t3-oss/env-core": "^0.13.11",
     "hast-util-to-string": "^3.0.1",
     "rehype-parse": "^9.0.1",
@@ -58,7 +58,7 @@
     "zod": "^4.6.5"
   },
   "devDependencies": {
-    "@g3nomaly/ui": "^0.3.6",
+    "@g3nomaly/ui": "^0.3.8",
     "@tanstack/react-router": "^1.170.41",
     "@tanstack/react-store": "^0.11.2",
     "@tree-sitter-grammars/tree-sitter-kotlin": "^1.1.0",