gitnexus 1.6.9 → 1.6.10-aptos.0

package/dist/core/analysis-features.js

@@ -0,0 +1,59 @@
+/**
+ * The Class table shape is global even when a repository contains no JVM code.
+ * Existing v8 indexes predate the frameworkAnnotations column and therefore
+ * need one full rebuild before any incremental Class write can be safe.
+ */
+export const CLASS_FRAMEWORK_ANNOTATIONS_FEATURE = {
+    id: 'graph.class-framework-annotations',
+    version: 1,
+    appliesTo: () => true,
+};
+/** Resolve the exact feature set this build promises for the supplied files. */
+export function resolveAnalysisFeatureVersions(descriptors, filePaths) {
+    const resolved = new Map();
+    const seenIds = new Set();
+    for (const descriptor of descriptors) {
+        if (descriptor.id.trim().length === 0) {
+            throw new Error('Analysis feature descriptor id must not be empty');
+        }
+        if (!Number.isSafeInteger(descriptor.version) || descriptor.version < 1) {
+            throw new Error(`Analysis feature "${descriptor.id}" has invalid version ${descriptor.version}`);
+        }
+        if (seenIds.has(descriptor.id)) {
+            throw new Error(`Duplicate analysis feature descriptor: ${descriptor.id}`);
+        }
+        seenIds.add(descriptor.id);
+        if (!descriptor.appliesTo(filePaths))
+            continue;
+        resolved.set(descriptor.id, descriptor.version);
+    }
+    return Object.fromEntries([...resolved].sort(([left], [right]) => left.localeCompare(right)));
+}
+/**
+ * Compare an untrusted metadata value with the exact capabilities produced by
+ * this build. Extra keys also mismatch: a rollback must rebuild instead of
+ * certifying graph semantics emitted only by a newer binary.
+ */
+export function findAnalysisFeatureMismatches(actual, expected) {
+    const expectedKeys = Object.keys(expected);
+    if (actual === undefined)
+        return expectedKeys.map((id) => `missing:${id}`);
+    if (actual === null || typeof actual !== 'object' || Array.isArray(actual)) {
+        return ['invalid:analysisFeatures'];
+    }
+    const stamped = actual;
+    const mismatches = [];
+    for (const id of expectedKeys) {
+        const value = stamped[id];
+        if (value === undefined)
+            mismatches.push(`missing:${id}`);
+        else if (value !== expected[id])
+            mismatches.push(`version:${id}`);
+    }
+    for (const id of Object.keys(stamped)) {
+        if (!Object.prototype.hasOwnProperty.call(expected, id)) {
+            mismatches.push(`unexpected:${id}`);
+        }
+    }
+    return mismatches.sort();
+}

package/dist/core/analyzer-identity.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Reproducible analyzer identity stamped into RepoMeta after a successful run.
+ *
+ * Schema v4 uses length-prefixed canonical frames. Build files and runtime
+ * artifacts contribute SHA-256 payload digests, so a validated stat inventory
+ * can safely reuse those expensive per-file digests across short-lived CLI and
+ * server-worker processes. The cache is only an optimization: malformed,
+ * mismatched, or missing entries are rehashed, and every identity calculation
+ * performs a final return-boundary inventory before returning.
+ *
+ * `invokedArtifact` remains in the receipt for diagnostics, but is deliberately
+ * excluded from semantic freshness. The CLI and the server analyze worker are
+ * different entry files inside the same build tree; alternating between them
+ * must not make an otherwise identical index stale.
+ */
+import type { AnalyzerRunnerIdentity } from '../storage/repo-manager.js';
+export declare const ANALYZER_RUNNER_IDENTITY_SCHEMA_VERSION: 4;
+export interface AnalyzerIdentityTraversalLimits {
+    buildEntries: number;
+    buildDepth: number;
+    buildBytes: number;
+    runtimePackages: number;
+    runtimeEdges: number;
+    runtimeEntries: number;
+    runtimeDepth: number;
+    runtimePayloads: number;
+    runtimeBytes: number;
+    resolutionAncestors: number;
+}
+export interface AnalyzerIdentityResolveOptions {
+    /** Override the persistent digest-cache directory (primarily for tests). */
+    cacheDirectory?: string;
+    /** Tighten traversal limits for constrained hosts/tests; never raises production bounds. */
+    traversalLimits?: Partial<AnalyzerIdentityTraversalLimits>;
+    /** Observe actual file payload reads; cache hits do not invoke this callback. */
+    onHashedInput?: (input: {
+        kind: 'build' | 'runtime-artifact';
+        path: string;
+        bytes: number;
+    }) => void;
+    /** Observe cold-path topology work; a complete cache hit emits nothing. */
+    onCacheMissWork?: (input: {
+        kind: 'directory-walk' | 'manifest-read';
+        path: string;
+    }) => void;
+    /** Observe complete return-boundary cache validations (primarily for tests). */
+    onCacheValidationPass?: (input: {
+        guardCount: number;
+    }) => void;
+}
+export type AnalyzerRunnerSemanticIdentity = Omit<AnalyzerRunnerIdentity, 'invokedArtifact'>;
+/**
+ * Normalize a raw diagnostic receipt for freshness comparison. The entrypoint
+ * is the only excluded field; malformed/legacy receipts never compare equal.
+ */
+export declare function normalizeAnalyzerRunnerIdentityForComparison(identity: unknown): AnalyzerRunnerSemanticIdentity | null;
+/** Resolve the identity of the analyzer build and runtime executing now. */
+export declare function resolveAnalyzerRunnerIdentity(analyzerModuleUrl: string, options?: AnalyzerIdentityResolveOptions): AnalyzerRunnerIdentity;
+/**
+ * Semantic freshness comparison. Both receipts must be well-formed schema-v4
+ * values; only the diagnostic entrypoint field is normalized away.
+ */
+export declare function analyzerRunnerIdentitiesEqual(indexedIdentity: unknown, currentIdentity: unknown): boolean;
+/**
+ * Capture analyzer identity before invoking a loader that may evaluate the
+ * analyzer module graph. The explicit receipt is then threaded into analysis
+ * and checked again immediately before metadata commit.
+ */
+export declare function captureAnalyzerIdentityBeforeLoad<T>(analyzerModuleUrl: string, loader: () => Promise<T>, options?: AnalyzerIdentityResolveOptions): Promise<{
+    runnerIdentity: AnalyzerRunnerIdentity;
+    loaded: T;
+}>;
+/** Re-resolve immediately before commit and reject analyzer mutation mid-run. */
+export declare function finalizeAnalyzerRunnerIdentity(analyzerModuleUrl: string, startedWith: AnalyzerRunnerIdentity, options?: AnalyzerIdentityResolveOptions): AnalyzerRunnerIdentity;