@g3nomaly/analyze 0.1.6 → 0.1.7

package/README.md

@@ -52,7 +52,11 @@ Hits that match the same way, with the same kind, type, title, summary, score an
 
 When nothing matches, `search` lists up to three weak matches by meaning instead, under a note and with `weak: true` in the JSON. Rewording the query often finds a better one. Output is markdown, or JSON with `--json`. `--from analyze_out/index.html` queries a built site without the repository. `g3n-analyze --help` lists every option, node kind, section and edge kind.
 
-`refs --depth <n>` follows the edges `n` hops, one hop at a time in each direction, and prints each hop indented under the reference it follows. A node is listed once. `--edge`, `--incoming` and `--outgoing` apply at every hop; `--kind` and `--section` only pick the node to start from. `refs` lists at most 50 references over every hop, or `-n`, and says how many more it left out. `path <from> <to>` follows edges the way they point, so `path a b` and `path b a` differ; `--edge` keeps it to some kinds. A name with spaces goes in quotes.
+`refs --depth <n>` follows the edges `n` hops, one hop at a time in each direction, and prints each hop indented under the reference it follows. A node is listed once. `--edge`, `--incoming` and `--outgoing` apply at every hop; `--kind` and `--section` only pick the node to start from. `refs` lists at most 50 references over every hop, or `-n`, and says how many more it left out. `path <from> <to>` follows edges the way they point, so `path a b` and `path b a` differ; `--edge` keeps it to some kinds. Without `--edge` it follows every kind but `mentions`, the links descriptions make; `--include-mentions` follows those too, and of equally short chains the one with the fewest `mentions` steps still wins. A name with spaces goes in quotes.
+
+A call, a function passed on and an import say where they are made: `calls (add.ts:86, 112)` is a call on lines 86 and 112 of `add.ts`, the file of the node the edge starts at. In the JSON, such a reference has `location`, with the `path` of that file and its `lines`; any other reference has `location: null`. The links to one node print on one line, `calls (app.ts:7), passes (app.ts:9): function run`, and a heading counts the lines under it.
+
+`refs --level files` lists the links between the file of the node and other files, the way the files level of the graph page draws them: every link of the file or of an entry in it, to another file or an entry in it, counts for that file. These are no links of their own. The default, `--level entries`, lists the links as they are stored.
 
 The commands exit with 0 when they answer, also for a search that finds nothing, with 1 for a node that does not exist, a name that fits several nodes, a `path` with no chain, or a repository or site that cannot be read, and with 2 for a call that is not valid, such as an unknown flag.
 
@@ -64,7 +68,7 @@ A **community** is a group of nodes that link to each other more than to the res
 
 ### How code links
 
-- **Imports**: C and C++ `#include`, JavaScript and TypeScript imports, and Python imports link to the file of the repository they name. An include resolves next to the including file, then against every file whose path ends with it, the closest winning. A TypeScript import resolves a relative path, a package of the repository by name (`@scope/core`), or a path alias (`@/lib/api`). A header or package from outside the repository links to nothing.
+- **Imports**: an import of a whole file links to that file: a C or C++ `#include`, a Python `import a.b`, and in JavaScript and TypeScript `import './x'`, `import * as x`, a default import, `export * from` and `require`. An import by name links to each class, function or type it names, through any `export … from` files in between, and not to the file: `import { recordedHashes } from "../../installer"` links to `recordedHashes` in `installer/classify.ts`, which `installer/index.ts` re-exports. Python's `from a import b` does the same for a `b` that is no module. A name that is no node, such as a constant, links to the file the import names. An include resolves next to the including file, then against every file whose path ends with it, the closest winning. A TypeScript import resolves a relative path, a package of the repository by name (`@scope/core`), or a path alias (`@/lib/api`). A header or package from outside the repository links to nothing. The files level of the graph page and of `graph` draws the links of a file to the entries of another file as one arrow between the files.
 - **What a file sees**: in C, C++, JavaScript, TypeScript and Python, a file sees itself and the files it imports, directly or through other files. A type name or a call only links to a declaration in a file it sees, so a common name never links across the repository. In the other languages every file is seen, and a type name links to the closest declaration of that name.
 - **Types**: a qualified C++ name such as `geo::Point` only links to a `Point` inside `geo`. A type declared in a C or C++ source file is seen only in that file.
 - **Calls**: a call links when it names one function: by name, through a namespace or type (`geo::distance()`, `Timer.once()`), through `this` or `self`, or through a parameter or field whose declared type is known. A call through a local variable, a module alias such as `helpers.go()`, or any other expression links nowhere, since its type is unknown. A bare call inside a JavaScript, TypeScript or Python method never means a method of its own class. A C++ method declared in a header and defined in a source file is called at its declaration. Only the calls inside a function or method link: code at the top level of a file, such as the callbacks a CLI registers there, belongs to no function.

package/dist/api/path.d.ts

@@ -6,7 +6,9 @@ import type { NodeFilter, NodeSummary, Reference, Retriever } from '../retrieval
  *
  * @property start - Id, path or name of the node the chain starts at. Not `from`, which names a site to read.
  * @property end - Id, path or name of the node the chain ends at.
- * @property edges - Only edges of these kinds. Empty or absent follows every kind.
+ * @property edges - Only edges of these kinds. Empty or absent follows every kind but `mentions`.
+ * @property includeMentions - Also follow `mentions`, the links descriptions make, when `edges` is empty. Of the
+ *   chains that are equally short, the one with the fewest `mentions` steps still wins.
  */
 declare const pathSchema: z.ZodPipe<z.ZodObject<{
     onWarning: z.ZodOptional<z.ZodCustom<import("./options").WarningHandler, import("./options").WarningHandler>>;
@@ -68,6 +70,7 @@ declare const pathSchema: z.ZodPipe<z.ZodObject<{
         uses: "uses";
         writes: "writes";
     }>>>>;
+    includeMentions: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>, z.ZodTransform<{
     source: import("./source").BundleSource;
     reporter: import("../scanner").Reporter;
@@ -76,6 +79,7 @@ declare const pathSchema: z.ZodPipe<z.ZodObject<{
         end: string;
         filter: NodeFilter;
         kinds: readonly ("affects" | "calls" | "depends" | "extends" | "imports" | "mentions" | "names" | "passes" | "reads" | "references" | "returns" | "throws" | "type" | "uses" | "writes")[];
+        includeMentions: boolean;
     };
 }, {
     onWarning?: import("./options").WarningHandler | undefined;
@@ -92,6 +96,7 @@ declare const pathSchema: z.ZodPipe<z.ZodObject<{
     start: string;
     end: string;
     edges?: readonly ("affects" | "calls" | "depends" | "extends" | "imports" | "mentions" | "names" | "passes" | "reads" | "references" | "returns" | "throws" | "type" | "uses" | "writes")[] | undefined;
+    includeMentions?: boolean | undefined;
 }>>;
 /** Options of `path`: the two nodes, the edges to follow, and the bundle to read. */
 export type PathOptions = z.input<typeof pathSchema>;
@@ -101,13 +106,15 @@ export type PathOptions = z.input<typeof pathSchema>;
  * @property start - Id, path or name of the node the chain starts at.
  * @property end - Id, path or name of the node the chain ends at.
  * @property filter - Narrows both names to one node each.
- * @property kinds - Edge kinds to follow. Empty follows every kind.
+ * @property kinds - Edge kinds to follow. Empty follows every kind but `mentions`, unless `includeMentions` is set.
+ * @property includeMentions - Whether an empty `kinds` follows `mentions` too.
  */
 export interface PathRequest {
     readonly start: string;
     readonly end: string;
     readonly filter: NodeFilter;
     readonly kinds: readonly EdgeKind[];
+    readonly includeMentions: boolean;
 }
 /**
  * What `path` finds. The CLI prints it with `path --json`.

package/dist/api/refs.d.ts

@@ -9,6 +9,8 @@ import { type NodeFilter, type NodeSummary, type Retriever, type Walk, type Walk
  * @property edges - Only edges of these kinds. Empty or absent keeps every kind.
  * @property depth - Hops to follow from the node. Default: 1, the node's own references.
  * @property limit - Most references to list, every hop and both directions together. Default: 50.
+ * @property level - `entries` for the stored links, `files` for the links between the files that hold their ends,
+ *   from the file of the node. Default: `entries`.
  */
 declare const refsSchema: z.ZodPipe<z.ZodObject<{
     onWarning: z.ZodOptional<z.ZodCustom<import("./options").WarningHandler, import("./options").WarningHandler>>;
@@ -73,6 +75,10 @@ declare const refsSchema: z.ZodPipe<z.ZodObject<{
     }>>>>;
     depth: z.ZodOptional<z.ZodNumber>;
     limit: z.ZodOptional<z.ZodNumber>;
+    level: z.ZodOptional<z.ZodEnum<{
+        entries: "entries";
+        files: "files";
+    }>>;
 }, z.core.$strict>, z.ZodTransform<{
     source: import("./source").BundleSource;
     reporter: import("../scanner").Reporter;
@@ -84,6 +90,7 @@ declare const refsSchema: z.ZodPipe<z.ZodObject<{
             kinds: readonly ("affects" | "calls" | "depends" | "extends" | "imports" | "mentions" | "names" | "passes" | "reads" | "references" | "returns" | "throws" | "type" | "uses" | "writes")[];
             depth: number;
             limit: number;
+            level: "entries" | "files";
         };
     };
 }, {
@@ -104,6 +111,7 @@ declare const refsSchema: z.ZodPipe<z.ZodObject<{
     edges?: readonly ("affects" | "calls" | "depends" | "extends" | "imports" | "mentions" | "names" | "passes" | "reads" | "references" | "returns" | "throws" | "type" | "uses" | "writes")[] | undefined;
     depth?: number | undefined;
     limit?: number | undefined;
+    level?: "entries" | "files" | undefined;
 }>>;
 /** Options of `refs`: the node, which links to follow and how far, and the bundle to read. */
 export type RefsOptions = z.input<typeof refsSchema>;
@@ -122,7 +130,7 @@ export interface RefsRequest {
 /**
  * What `refs` finds. The CLI prints it with `refs --json`.
  *
- * @property node - The node the references are of.
+ * @property node - The node the references are of: the file of the target at the `files` level.
  */
 export interface RefsResult extends Walk {
     readonly node: NodeSummary;