gitnexus 1.6.9 → 1.6.10-aptos.1

package/dist/core/move/constants.js

@@ -0,0 +1,136 @@
+/**
+ * Shared Move/Aptos constants and helpers — single source of truth for the
+ * magic strings that span the mapper, the ingest phase, the entry-point linker,
+ * and the MCP backend. A typo in any duplicated literal silently breaks a query
+ * with no compile error, so they live here.
+ */
+import path from 'node:path';
+/** `NodeProperties.language` tag for every Move symbol. */
+export const MOVE_LANGUAGE = 'move';
+/**
+ * Parsed Move attribute names of interest. The mapper persists the full
+ * attribute list on every Function node as `attributes: STRING[]`, so the
+ * canonical Cypher query is `WHERE '<name>' IN f.attributes`. These constants
+ * exist so the mapper, downstream filters, and tests share a typo-resistant
+ * single source of truth for the names that matter (compiler attribute names
+ * follow the move-flow `facts` payload verbatim).
+ */
+export const MOVE_ATTR = {
+    EVENT: 'event',
+    /** `#[persistent]` — vault burn reentrancy guard and similar invariants. */
+    PERSISTENT: 'persistent',
+    /** `#[randomness]` — randomness-attestation entry function. */
+    RANDOMNESS: 'randomness',
+    /** `#[deprecated]` — marked obsolete; flagged by Move lints. */
+    DEPRECATED: 'deprecated',
+    /** `#[lint::skip(...)]` — suppresses one or more Move lints. */
+    LINT_SKIP: 'lint::skip',
+    /** `#[resource_group(scope = ...)]` - declares a resource group. */
+    RESOURCE_GROUP: 'resource_group',
+    /** `#[resource_group_member(group = <qualified struct>)]` - group membership. */
+    RESOURCE_GROUP_MEMBER: 'resource_group_member',
+    /** `#[verify_only]` — visible to the Move Prover only; excluded from runtime. */
+    VERIFY_ONLY: 'verify_only',
+    /** `#[view]` — read-only view function. */
+    VIEW: 'view',
+};
+/** Move struct abilities of interest. */
+export const MOVE_ABILITY = {
+    KEY: 'key',
+};
+/**
+ * `reason` strings for Move graph edges.
+ *
+ * Note on `friend`: move-flow's `friends` array on a module is a *compiler-
+ * derived* set that conflates two source-level concepts: explicit
+ * `friend X::Y;` declarations and the Move-2 cross-module visibility that
+ * `package fun` (and friend-restricted `public(friend)`) implicitly grants.
+ * The facts payload does not preserve which of the two produced each entry,
+ * so the `move-friend-or-package` reason is intentionally ambiguous; a
+ * downstream filter (e.g. re-parsing source) is needed to distinguish them.
+ */
+export const MOVE_EDGE_REASON = {
+    definesFunction: 'move-module-defines-function',
+    definesStruct: 'move-module-defines-struct',
+    definesEnum: 'move-module-defines-enum',
+    definesConst: 'move-module-defines-const',
+    containsVariant: 'move-enum-contains-variant',
+    friend: 'move-friend-or-package',
+    calls: 'move-compiler-call-graph',
+    crossModuleDependency: 'move-cross-module-dependency',
+    moduleInFile: 'move-module-in-file',
+    // Resource-access edges (function → resource struct)
+    readsResource: 'move-reads_resource',
+    writesResource: 'move-writes_resource',
+    acquires: 'move-acquires',
+    fnParamType: 'move-fn-param-type',
+    fnReturnType: 'move-fn-return-type',
+    // Struct -> resource-group struct (from `#[resource_group_member(group = ...)]`)
+    resourceGroupMember: 'move-resource-group-member',
+    // Field edges (struct → field)
+    hasField: 'move-struct-has-field',
+    // Lambda → host edges (host fn → __lambda__N__host)
+    lambdaHost: 'move-lambda-of-host',
+    // Entry-point edge reasons (ENTRY_POINT_OF)
+    entryFunction: 'move-entry-function',
+    viewFunction: 'move-view-function',
+};
+/** Error-code constant naming convention (e.g. `E_NOT_REGISTERED`). */
+export const ERROR_CODE_PATTERN = /^E[_A-Z]/;
+/** True when a file can change compiler facts for an entire Move package. */
+export function isMoveCompilerInputPath(filePath) {
+    const normalized = filePath.replaceAll('\\', '/');
+    const basename = normalized.slice(normalized.lastIndexOf('/') + 1);
+    return normalized.endsWith('.move') || basename === 'Move.toml' || basename === 'Move.lock';
+}
+function sameMoveFlowReleaseSelection(left, right) {
+    return (left !== undefined &&
+        right !== undefined &&
+        left.version === right.version &&
+        left.repository === right.repository &&
+        left.tag === right.tag &&
+        left.assetName === right.assetName);
+}
+/** Legacy metadata with recorded Move inputs is treated conservatively. */
+export function persistedMoveGraphRequiresCompiler(moveIngestAvailable, fileHashes) {
+    if (moveIngestAvailable !== undefined)
+        return moveIngestAvailable;
+    return Object.keys(fileHashes ?? {}).some(isMoveCompilerInputPath);
+}
+/** Decide whether managed provisioning must run before the clean-repo fast path. */
+export function shouldProvisionMoveFlowBeforeFastPath(hasMovePackages, persistedGraphRequiresCompiler, indexedCompiler, indexedRelease, desiredRelease) {
+    if (!hasMovePackages)
+        return false;
+    if (!persistedGraphRequiresCompiler)
+        return true;
+    if (!indexedCompiler)
+        return true;
+    if (indexedCompiler.source !== 'release')
+        return false;
+    return !sameMoveFlowReleaseSelection(indexedRelease, desiredRelease);
+}
+/** Compiler-backed facts must be rebuilt when their producer changes. */
+export function moveCompilerRequiresFullRebuild(hasMovePackages, compiler, indexedWithCompiler, indexedCompiler) {
+    if (!hasMovePackages || !compiler)
+        return false;
+    return (indexedWithCompiler !== true ||
+        !indexedCompiler ||
+        indexedCompiler.version !== compiler.version ||
+        indexedCompiler.source !== compiler.source ||
+        indexedCompiler.fingerprint !== compiler.fingerprint);
+}
+/**
+ * Make an absolute path repo-relative so node IDs and `File:` node links align.
+ * Returns the input unchanged when `repoPath` is absent or non-matching.
+ */
+export function moveRepoRelativePath(absPath, repoPath) {
+    if (!repoPath)
+        return absPath;
+    const relative = path.relative(repoPath, absPath);
+    if (relative === '')
+        return relative;
+    if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+        return absPath;
+    }
+    return relative.replaceAll(path.sep, '/');
+}

package/dist/core/move/discovery.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Move project discovery utilities.
+ *
+ * Cross-platform: uses the `glob` package instead of shelling out to the
+ * POSIX-only `find` command, so this works on native Windows.
+ */
+/**
+ * Returns true when the repo contains at least one Move.toml.
+ */
+export declare function repoHasMove(repoPath: string): Promise<boolean>;

package/dist/core/move/discovery.js

@@ -0,0 +1,22 @@
+/**
+ * Move project discovery utilities.
+ *
+ * Cross-platform: uses the `glob` package instead of shelling out to the
+ * POSIX-only `find` command, so this works on native Windows.
+ */
+import { globIterate } from 'glob';
+/**
+ * Returns true when the repo contains at least one Move.toml.
+ */
+export async function repoHasMove(repoPath) {
+    for await (const _match of globIterate(['**/Move.toml'], {
+        cwd: repoPath,
+        ignore: ['**/node_modules/**', '**/.git/**', '**/dist/**', '**/build/**'],
+        nodir: true,
+        absolute: false,
+        dot: false,
+    })) {
+        return true;
+    }
+    return false;
+}

package/dist/core/move/entry-points.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Move entry point detection.
+ *
+ * Creates ENTRY_POINT_OF edges for Move functions that serve as external
+ * entry points into the contract:
+ *   - entry functions (transaction entry points)
+ *   - #[view] functions (read-only API queries)
+ *
+ * Must run AFTER moveIngest, which creates the Function nodes and sets the
+ * isEntry/isView flags from compiler facts.
+ */
+import type { KnowledgeGraph } from '../graph/types.js';
+import type { MoveIngestOutput } from './move-ingest.js';
+export declare function createMoveEntryPointEdges(graph: KnowledgeGraph, moveIngest: MoveIngestOutput): void;

package/dist/core/move/entry-points.js

@@ -0,0 +1,40 @@
+/**
+ * Move entry point detection.
+ *
+ * Creates ENTRY_POINT_OF edges for Move functions that serve as external
+ * entry points into the contract:
+ *   - entry functions (transaction entry points)
+ *   - #[view] functions (read-only API queries)
+ *
+ * Must run AFTER moveIngest, which creates the Function nodes and sets the
+ * isEntry/isView flags from compiler facts.
+ */
+import { moveModuleNodeId, moveModuleQualifiedName, moveRelId } from './symbol-id.js';
+import { MOVE_EDGE_REASON } from './constants.js';
+export function createMoveEntryPointEdges(graph, moveIngest) {
+    for (const [funcQualified, funcNodeId] of moveIngest.functionNodeMap) {
+        const funcNode = graph.getNode(funcNodeId);
+        if (!funcNode)
+            continue;
+        const isEntry = funcNode.properties.isEntry === true;
+        const isView = funcNode.properties.isView === true;
+        if (!isEntry && !isView)
+            continue;
+        const moduleQualified = moveModuleQualifiedName(funcQualified);
+        const moduleFilePath = moveIngest.moduleFileMap.get(moduleQualified);
+        if (!moduleFilePath)
+            continue;
+        const moduleNodeId = moveModuleNodeId(moduleQualified, moduleFilePath);
+        if (!graph.getNode(moduleNodeId))
+            continue;
+        const reason = isEntry ? MOVE_EDGE_REASON.entryFunction : MOVE_EDGE_REASON.viewFunction;
+        graph.addRelationship({
+            id: moveRelId(funcNodeId, 'ENTRY_POINT_OF', moduleNodeId, reason),
+            sourceId: funcNodeId,
+            targetId: moduleNodeId,
+            type: 'ENTRY_POINT_OF',
+            confidence: 1.0,
+            reason,
+        });
+    }
+}

package/dist/core/move/facts-mapper.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Thin facts → graph mapper.
+ *
+ * Consumes the move-flow `facts` query response (the compiler's full-fidelity,
+ * per-module structured facts) and produces standard GraphNode / GraphRelationship
+ * objects. This is the heart of the compiler-first Move ingestion: there is
+ * **no raw-source scanning** — every fact (visibility, entry/view, attributes,
+ * acquires, resource reads/writes, enum variants, friends, locations) comes
+ * straight from move-flow.
+ */
+import type { GraphNode, GraphRelationship, NodeLabel, RelationshipType } from '../../_shared/index.js';
+import type { MoveFactsMap } from './compiler-facts.js';
+export interface MoveFactsMapResult {
+    nodes: GraphNode[];
+    edges: GraphRelationship[];
+    /** Module qualified name → source file path. */
+    moduleFileMap: Map<string, string>;
+    /** Function qualified name → graph node ID. */
+    functionNodeMap: Map<string, string>;
+    /** Struct/enum qualified name → graph node ID. */
+    structNodeMap: Map<string, string>;
+    /** Resource edges that need the full cross-package type index. */
+    pendingResource: PendingResource[];
+    /** Friend edges that need the full cross-package module index. */
+    pendingFriends: PendingFriend[];
+    /** Signature type refs that need the full cross-package type index. */
+    pendingTypeRef: PendingTypeRef[];
+    /** Lambda → host links that need the host's Function node id (resolved post-pass). */
+    pendingLambdaHosts: PendingLambdaHost[];
+}
+export interface PendingLambdaHost {
+    /** The lambda's Function node id (target of the CALLS edge). */
+    lambdaFnNodeId: string;
+    /** Host function's fully-qualified name (`<module>::<localHost>`). */
+    hostQualified: string;
+}
+export interface PendingResource {
+    fnNodeId: string;
+    moduleQualified: string;
+    type: RelationshipType;
+    target: string;
+    reason: string;
+}
+export interface PendingFriend {
+    moduleNodeId: string;
+    friend: string;
+}
+export interface PendingTypeRef {
+    /** Source node of the USES_TYPE edge - a Function, or a Struct for
+     *  `resource_group_member` membership refs. */
+    sourceNodeId: string;
+    moduleQualified: string;
+    target: string;
+    reason: string;
+}
+/**
+ * Map a full `facts` response (covering every module in a package) to graph
+ * nodes + edges. `packageRoot` is used only as a location fallback when the
+ * compiler omits a per-symbol file (it never does today, but the field is
+ * optional in the schema). When `repoPath` is given, absolute file paths from
+ * the compiler are made repo-relative so node IDs align with `File:` nodes.
+ */
+export declare function mapFactsToGraph(facts: MoveFactsMap, packageRoot: string, repoPath?: string): MoveFactsMapResult;
+/**
+ * Resolve queued lambda→host links into CALLS edges. Run after every package's
+ * facts have been mapped so the host's Function node is guaranteed to exist
+ * (the host may be defined in a different module within the package, or — for
+ * cross-package lambda capture — in another package altogether).
+ */
+export declare function resolveLambdaHostEdges(pendingLambdaHosts: readonly PendingLambdaHost[], functionNodeMap: ReadonlyMap<string, string>, edgeSink: (rel: GraphRelationship) => void): void;
+export declare function buildLocalNameIndex(structNodeMap: ReadonlyMap<string, string>): Map<string, string[]>;
+export declare function resolveResourceEdges(pendingResource: readonly PendingResource[], structNodeMap: ReadonlyMap<string, string>, structIdsByLocalName: ReadonlyMap<string, readonly string[]>, edgeSink: (rel: GraphRelationship) => void, onUnresolved?: (pending: PendingResource) => void, onAmbiguous?: (pending: PendingResource) => void): void;
+export declare function resolveFriendEdges(pendingFriends: readonly PendingFriend[], moduleFileMap: ReadonlyMap<string, string>, edgeSink: (rel: GraphRelationship) => void): void;
+export declare function resolveTypeRefEdges(pendingTypeRef: readonly PendingTypeRef[], structNodeMap: ReadonlyMap<string, string>, structIdsByLocalName: ReadonlyMap<string, readonly string[]>, edgeSink: (rel: GraphRelationship) => void, onUnresolved?: (pending: PendingTypeRef) => void, onAmbiguous?: (pending: PendingTypeRef) => void): void;
+export type { NodeLabel };