gitnexus 1.6.11-rc.8 → 1.6.11

package/dist/core/ingestion/pipeline-phases/scan.js

@@ -10,6 +10,79 @@
  * @output  ScannedFile[], allPaths[], totalFiles
  */
 import { walkRepositoryPaths } from '../filesystem-walker.js';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+const SPRING_ACTUATOR_ENDPOINT_FILES = new Set([
+    'mappings.json',
+    'beans.json',
+    'conditions.json',
+    'configprops.json',
+    'env.json',
+]);
+async function canonicalPath(filePath) {
+    return fs.realpath(filePath).catch(() => path.resolve(filePath));
+}
+async function compileActuatorExclusions(repoPath, inputPaths) {
+    const repo = await canonicalPath(repoPath);
+    const lexicalRepo = path.resolve(repoPath);
+    const compiled = [];
+    const seen = new Set();
+    for (const inputPath of inputPaths) {
+        const lexicalInput = path.resolve(repoPath, inputPath);
+        const lexicalRelative = path.relative(lexicalRepo, lexicalInput);
+        const canonicalInput = await canonicalPath(lexicalInput);
+        const candidateInputs = new Set([canonicalInput]);
+        if (lexicalRelative === '' ||
+            (lexicalRelative !== '..' &&
+                !lexicalRelative.startsWith(`..${path.sep}`) &&
+                !path.isAbsolute(lexicalRelative))) {
+            // Preserve the configured in-repo alias as an exclusion even when its
+            // real target is outside the repository.
+            candidateInputs.add(path.resolve(repo, lexicalRelative));
+        }
+        for (const input of candidateInputs) {
+            const inputRelativeToRepo = path.relative(repo, input);
+            if (inputRelativeToRepo === '') {
+                if (seen.has(''))
+                    continue;
+                seen.add('');
+                compiled.push({ kind: 'repo-root-endpoints' });
+                continue;
+            }
+            if (inputRelativeToRepo === '..' ||
+                inputRelativeToRepo.startsWith(`..${path.sep}`) ||
+                path.isAbsolute(inputRelativeToRepo)) {
+                continue;
+            }
+            if (seen.has(input))
+                continue;
+            seen.add(input);
+            compiled.push({ kind: 'dir', resolved: input });
+        }
+    }
+    return { repo, exclusions: compiled };
+}
+function matchesActuatorExclusion(canonicalRepoPath, filePath, exclusions) {
+    if (exclusions.length === 0)
+        return false;
+    const candidate = path.resolve(canonicalRepoPath, filePath);
+    for (const exclusion of exclusions) {
+        if (exclusion.kind === 'repo-root-endpoints') {
+            const candidateRelativeToRepo = path.relative(canonicalRepoPath, candidate);
+            if (path.dirname(candidateRelativeToRepo) === '.' &&
+                SPRING_ACTUATOR_ENDPOINT_FILES.has(path.basename(candidateRelativeToRepo).toLowerCase())) {
+                return true;
+            }
+            continue;
+        }
+        const relative = path.relative(exclusion.resolved, candidate);
+        if (relative === '' ||
+            (relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative))) {
+            return true;
+        }
+    }
+    return false;
+}
 export const scanPhase = {
     name: 'scan',
     deps: [],
@@ -19,15 +92,20 @@ export const scanPhase = {
             percent: 0,
             message: 'Scanning repository...',
         });
+        const { repo: canonicalRepoPath, exclusions: actuatorExclusions } = await compileActuatorExclusions(ctx.repoPath, [
+            ...(ctx.options?.springActuatorPath === undefined ? [] : [ctx.options.springActuatorPath]),
+            ...(ctx.options?.springActuatorScanExclusions ?? []),
+        ]);
         let scannedFiles;
         try {
             scannedFiles = await walkRepositoryPaths(ctx.repoPath, (current, total, filePath) => {
                 const scanProgress = Math.round((current / total) * 15);
+                const isRuntimeInput = matchesActuatorExclusion(canonicalRepoPath, filePath, actuatorExclusions);
                 ctx.onProgress({
                     phase: 'extracting',
                     percent: scanProgress,
                     message: 'Scanning repository...',
-                    detail: filePath,
+                    ...(isRuntimeInput ? {} : { detail: filePath }),
                     stats: {
                         filesProcessed: current,
                         totalFiles: total,
@@ -45,6 +123,9 @@ export const scanPhase = {
             }
             throw err;
         }
+        if (actuatorExclusions.length > 0) {
+            scannedFiles = scannedFiles.filter((file) => !matchesActuatorExclusion(canonicalRepoPath, file.path, actuatorExclusions));
+        }
         const totalFiles = scannedFiles.length;
         const allPaths = scannedFiles.map((f) => f.path);
         ctx.onProgress({

package/dist/core/ingestion/pipeline-phases/spring-auto-configuration.d.ts

@@ -10,6 +10,7 @@
  * @reads   META-INF/spring.factories and AutoConfiguration.imports
  * @writes  Class nodes and DECLARES edges
  */
+import { type SpringActuatorImportStats } from '../frameworks/spring/actuator-runtime.js';
 import type { PipelinePhase } from './types.js';
 export interface SpringAutoConfigurationEntry {
     readonly className: string;
@@ -24,6 +25,7 @@ export interface SpringAutoConfigurationOutput {
     readonly metadataFiles: number;
     readonly autoConfigurations: number;
     readonly ambiguousAutoConfigurations: number;
+    readonly actuatorRuntime?: SpringActuatorImportStats;
 }
 export declare function classifySpringAutoConfigurationMetadata(filePath: string): SpringAutoConfigurationMetadataFile | null;
 /** Parse Boot 2.7+/3.x one-class-per-line auto-configuration imports. */

package/dist/core/ingestion/pipeline-phases/spring-auto-configuration.js

@@ -15,6 +15,7 @@ import path from 'node:path';
 import { generateId } from '../../../lib/utils.js';
 import { logger } from '../../logger.js';
 import { SPRING_AUTO_CONFIGURATION_FACTORY_REASON, SPRING_AUTO_CONFIGURATION_IMPORT_REASON, SPRING_AUTO_CONFIGURATION_SYNTHETIC_DESCRIPTION, } from '../frameworks/spring/auto-configuration.js';
+import { importSpringActuatorRuntime, MAX_RUNTIME_RECORDS, } from '../frameworks/spring/actuator-runtime.js';
 import { isDev } from '../utils/env.js';
 import { getPhaseOutput } from './types.js';
 const MAX_SPRING_METADATA_BYTES = 2 * 1024 * 1024;
@@ -246,10 +247,17 @@ export const springAutoConfigurationPhase = {
             logger.debug(`Spring auto-configuration: skipped ${ambiguousQualifiedNames.size} ambiguous FQN(s) ` +
                 `because classpath precedence is unknown: ${[...ambiguousQualifiedNames].sort().join(', ')}`);
         }
+        const actuatorRuntime = ctx.options?.springActuatorPath === undefined
+            ? undefined
+            : await importSpringActuatorRuntime(ctx.graph, ctx.repoPath, ctx.options.springActuatorPath);
+        if (actuatorRuntime !== undefined && actuatorRuntime.truncatedEndpoints.length > 0) {
+            logger.warn(`Spring Actuator runtime import reached the ${MAX_RUNTIME_RECORDS.toLocaleString('en-US')}-record limit for: ${actuatorRuntime.truncatedEndpoints.join(', ')}. Runtime evidence is incomplete.`);
+        }
         return {
             metadataFiles,
             autoConfigurations,
             ambiguousAutoConfigurations: ambiguousQualifiedNames.size,
+            ...(actuatorRuntime === undefined ? {} : { actuatorRuntime }),
         };
     },
 };

package/dist/core/ingestion/pipeline-phases/spring-destinations.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Phase: springDestinations
+ *
+ * Materializes Spring async messaging as graph structure: a `Destination` node
+ * per broker address, `CONSUMES_FROM` from every `@KafkaListener`-family
+ * handler, and `PUBLISHES_TO` from every messaging-template publish. The
+ * inbound and outbound facts are captured during parse and survive the parse
+ * cache; until now nothing read them.
+ *
+ * Since `asyncApiSpecPath`, the phase has a SECOND source that is not Spring
+ * and not source code at all: AsyncAPI documents read off disk
+ * (`ingestion/asyncapi/document.ts`). They mint the same `Destination` nodes on
+ * the same key, so both sources meet on one node. The reader is deliberately
+ * framework-neutral and lives outside `frameworks/spring/`; only the emit is
+ * hosted here, because this is where the node's keying rule is enforced and
+ * splitting that rule across two phases is how it drifts. The phase name is
+ * accurate about its origin rather than its current contents.
+ *
+ * Shaped after `Route` + `HANDLES_ROUTE` in `routes.ts` — a framework overlay
+ * node keyed by what it names, with the callable pointing at it, down to the
+ * detail that the key pairs the address with the one dimension that can make
+ * two same-named things different places: the method for a Route, the broker
+ * here.
+ *
+ * ── THE KEYING RULE, WHICH IS THE POINT OF THE PHASE ─────────────────────
+ *
+ * A `Destination` connects two services precisely because both sides mint the
+ * SAME node id from the SAME address on the SAME broker. That is the whole
+ * value, and it is also the whole hazard: an address that could not be resolved
+ * must never be allowed to key a node.
+ *
+ *     resolved    id = generateId('Destination', `<broker> <address>`)  `address` present
+ *     unresolved  id = generateId('Destination', <site>)                `address` ABSENT
+ *
+ * Two unrelated services that each merely write `@KafkaListener(topics =
+ * "${app.topic}")` have said nothing whatever about each other. Keyed on the
+ * placeholder text they would land on one node and READ AS CONNECTED, in a
+ * report, as a fact. A missing edge is visible as a gap; a false one is not.
+ *
+ * A status property would not have prevented this, and neither would a second
+ * label: the id is what merges the nodes, and both sides would still compute
+ * the same id. Only the KEY prevents it, so an unresolved destination is keyed
+ * by its source LOCATION — a value no second file can produce.
+ *
+ * The same rule governs the `address` PROPERTY, which is the join key a
+ * cross-repository pass would match on. It is written only when resolved. An
+ * absent property cannot match another absent property, so the structural
+ * guarantee survives being read back out of the database. The unresolved
+ * spelling is kept in `name`, for a human reading the node.
+ *
+ * The BROKER is part of the connecting key rather than a reason to withdraw
+ * one — see {@link destinationNodeKey}, which owns that argument and the
+ * evidence for it. Two brokers claiming one address is therefore an ordinary
+ * two-node situation here, exactly like `GET /x` and `POST /x`, and this phase
+ * needs no vocabulary for it: nothing is being taken away, so there is nothing
+ * to diagnose.
+ *
+ * `name` must never be used to join two destinations, and nothing does — but
+ * the stronger claim that nothing reads it at all would be false. `Destination`
+ * is in `VALID_NODE_LABELS`, and `mcp/local/local-backend.ts` resolves a
+ * symbol with an unlabeled `WHERE n.name = $symName`, so a destination can be
+ * returned by name like any other node. That is a lookup, not a join: it
+ * matches a caller-supplied string against one node, never one destination
+ * against another, so it cannot manufacture the connection this phase exists to
+ * prevent.
+ *
+ * @deps    parse, scopeResolution, springConfig
+ * @reads   Spring messaging capture facts, Method/Function nodes, Property nodes,
+ *          AsyncAPI documents under `options.asyncApiSpecPath` (filesystem)
+ * @writes  Destination nodes; synthetic File nodes for out-of-tree documents;
+ *          CONSUMES_FROM / PUBLISHES_TO / USES edges
+ */
+import type { PipelinePhase } from './types.js';
+export interface SpringDestinationsOutput {
+    /** Destination nodes keyed by `(broker, address)`, and which therefore
+     *  connect to every other site that named the same address on the same
+     *  broker. */
+    readonly resolvedDestinations: number;
+    /** Destination nodes keyed by source location, and therefore unable to
+     *  connect: the address did not resolve. */
+    readonly unresolvedDestinations: number;
+    /** CONSUMES_FROM + PUBLISHES_TO edges emitted. */
+    readonly edges: number;
+    /**
+     * Every refusal, counted by reason. This is the phase's real measure: the
+     * feature is judged on the unresolved FRACTION, and a silent skip would hide
+     * exactly the number that says whether it works.
+     */
+    readonly refusalsByReason: Readonly<Record<string, number>>;
+    /** Destination -> Property provenance edges for `${key}` placeholders. */
+    readonly configKeyLinks: number;
+    /**
+     * What reading AsyncAPI documents contributed, present only when
+     * `asyncApiSpecPath` was configured. Absent means "not asked for", which is
+     * deliberately distinguishable from a configured path that yielded nothing —
+     * a mistyped directory and a repository with no documents are different
+     * problems with different fixes, and one zero cannot say which happened.
+     */
+    readonly specDocuments?: SpecDocumentStats;
+}
+export interface SpecDocumentStats {
+    /** Entries skipped because they were symbolic links, and whether a bound
+     *  stopped the walk. Both make every other number here a FLOOR, and a floor
+     *  reported as a total is the failure this whole block exists to prevent. */
+    readonly symlinksSkipped: number;
+    readonly truncated: boolean;
+    /** Files considered under the configured path. */
+    readonly scanned: number;
+    /** Files that parsed as an AsyncAPI 3.x document and yielded an operation. */
+    readonly accepted: number;
+    /** Operations normalized to a (broker, address, action) triple. */
+    readonly operations: number;
+    /** Destination nodes this reading minted that no source site had already. */
+    readonly destinations: number;
+    /** CONSUMES_FROM + PUBLISHES_TO edges from documents. */
+    readonly edges: number;
+    /** Document- and operation-level refusals, by reason. Kept apart from
+     *  `refusalsByReason` above: that number is the denominator of the SOURCE
+     *  unresolved fraction, and a mistyped specification directory must not be
+     *  able to make the source look worse than it is. */
+    readonly refusalsByReason: Readonly<Record<string, number>>;
+}
+export declare const springDestinationsPhase: PipelinePhase<SpringDestinationsOutput>;