[${options.languageLabel}-package-siblings] skipping package

Error message

[${options.languageLabel}-package-siblings] skipping package with ${bucket.moduleScopes.length} files (cap=${MAX_PACKAGE_FILES}); same-package implicit visibility disabled for this package

What it means

GitNexus caps same-package sibling processing at MAX_PACKAGE_FILES = 500 files per package to bound ingestion cost. When a package bucket holds more than 500 module scopes, the whole bucket is skipped: no same-package implicit visibility is injected, every file in it is marked visibility-incomplete, and this warning is emitted. GITNEXUS_MAX_INJECTED_SIBLINGS only bounds injection within processed packages — it does not lift this skip.

Source

Thrown at gitnexus/src/core/ingestion/languages/jvm/package-siblings.ts:101

    // A file whose package cannot be proven may shadow a wildcard-imported
    // type in any package. Conservatively disable wildcard attribution for the
    // language workspace while leaving explicit/FQN imports available.
    if (unknownPackageFiles.size > 0) {
      for (const parsed of parsedFiles) incompleteFiles.add(parsed.filePath);
      logger.warn(
        `[${options.languageLabel}-package-siblings] ${unknownPackageFiles.size} file(s) lacked reliable package facts; wildcard attribution disabled for this language workspace`,
      );
    }

    const augmentations = indexes.bindingAugmentations as Map<ScopeId, Map<string, BindingRef[]>>;
    const maxInjectedSiblings = getMaxInjectedSiblings();
    let truncatedFiles = 0;

    for (const bucket of buckets.values()) {
      if (bucket.moduleScopes.length < 2) continue;
      if (bucket.moduleScopes.length > MAX_PACKAGE_FILES) {
        for (const parsed of bucket.parsed) incompleteFiles.add(parsed.filePath);
        logger.warn(
          `[${options.languageLabel}-package-siblings] skipping package with ${bucket.moduleScopes.length} files (cap=${MAX_PACKAGE_FILES}); same-package implicit visibility disabled for this package`,
        );
        continue;
      }

      const classDefs: { def: BindingRef['def']; filePath: string }[] = [];
      for (const parsed of bucket.parsed) {
        const moduleScopeId = parsed.scopes.find((scope) => scope.kind === 'Module')?.id;
        for (const scope of parsed.scopes) {
          if (scope.kind !== 'Class' || scope.parent !== moduleScopeId) continue;
          const def = scope.ownedDefs.find((candidate) => isClassLike(candidate.type));
          if (def !== undefined) classDefs.push({ def, filePath: parsed.filePath });
        }
      }

      // Per-bucket lookups: the per-file loop below is O(files²) over these,
      // so split each path into segments once here instead of re-splitting it
      // on every pairwise proximity comparison, and address siblings by path

View on GitHub (pinned to aac7515d2a)

Solutions

Identify the oversized package and split it into sub-packages in the source
Exclude generated/vendored members of that package via .gitnexusignore and re-run analyze
Accept degraded same-package/wildcard visibility for that package — explicit imports still resolve
Do not bother raising GITNEXUS_MAX_INJECTED_SIBLINGS: the 500-file package cap is hard-coded and independent

Defensive patterns

Strategy: validation

Validate before calling

// Pre-flight: count parsed files per package; flag anything over the 500-file cap
const byPkg = new Map();
for (const f of javaFiles) {
  const m = readFileSync(f, 'utf8').match(/^package\s+([\w.]+);/m);
  const pkg = m ? m[1] : '(default)';
  byPkg.set(pkg, (byPkg.get(pkg) ?? 0) + 1);
}
for (const [pkg, n] of byPkg) if (n > 500) console.error(`package ${pkg} has ${n} files — same-package visibility will be skipped`);

Prevention

Keep packages under a few hundred files; split generator output into sub-packages
Exclude bulk-generated trees from analysis with .gitnexusignore
Treat any isVisibilityIncomplete answers for huge packages as low-trust in downstream tooling

When it happens

Trigger: A Java/Kotlin workspace where a single declared package (or the default package) spans more than 500 parsed files, so bucket.moduleScopes.length > 500 and the loop continues past the bucket.

Common situations: Code generators emitting thousands of classes into one package, legacy code in the default package, massive flat util packages, or vendored SDKs sharing one package namespace.

Related errors

AI-assisted analysis of abhigyanpatwari/GitNexus@aac7515d2a (2026-08-20). Data as JSON: /api/errors/fbeefb17b44c60a8. Report an issue: GitHub.