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

Error message

[${options.languageLabel}-package-siblings] ${unknownPackageFiles.size} file(s) lacked reliable package facts; wildcard attribution disabled for this language workspace

What it means

During JVM-language (Java/Kotlin) ingestion, GitNexus buckets parsed files by package to simulate same-package implicit visibility for wildcard imports. A file whose package cannot be proven (getPackageFact returns undefined) may shadow any wildcard-imported type, so the indexer conservatively disables wildcard attribution for the entire language workspace, marks the unknown-package files incomplete, and warns. Explicit and fully-qualified-name imports still resolve; only wildcard/same-package inference is degraded.

Source

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

        unknownPackageFiles.add(parsed.filePath);
        continue;
      }
      const packageName = packageFact.packageName;
      const bucket = buckets.get(packageName) ?? { parsed: [], moduleScopes: [] };
      buckets.set(packageName, bucket);
      bucket.parsed.push(parsed);
      const moduleScope = parsed.scopes.find((scope) => scope.kind === 'Module');
      if (moduleScope !== undefined) {
        bucket.moduleScopes.push({ filePath: parsed.filePath, scope: moduleScope });
      }
    }

    // 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;
      }

View on GitHub (pinned to aac7515d2a)

Solutions

Verify the affected files carry a valid, first-statement package declaration (Java) or correct build metadata (Kotlin)
Check .gitnexusignore is not excluding build files (pom.xml, build.gradle.kts) that supply package facts, then re-run analyze
If the files are generated/vendored and irrelevant, exclude them via .gitnexusignore and re-analyze
Accept the degradation when wildcard-resolution precision is not needed — explicit and FQN imports still resolve

Example fix

// before — src/generated/Template.java (no package declaration)
public class Template { /* ... */ }

// after
package com.acme.generated;
public class Template { /* ... */ }

Defensive patterns

Strategy: validation

Validate before calling

// Pre-flight: every .java file must declare a package on the first non-comment line
import { readFileSync } from 'node:fs';
const bad = files.filter((f) => f.endsWith('.java') && !/^\s*(\/\/.*\n|\/\*[\s\S]*?\*\/\s*)*package\s+[\w.]+;/.test(readFileSync(f, 'utf8')));
if (bad.length > 0) console.error('package-facts will be unreliable for:', bad);

Prevention

Keep a lint rule (e.g. eslint/spotless 'require-package' or checkstyle RegexpSingleline) enforcing Java package declarations in CI
Do not .gitnexusignore build files that supply Kotlin/Java package facts
Run a pre-analyze sanity script listing files without package declarations and fix or exclude them

When it happens

Trigger: populateNamespaceSiblings runs over parsedFiles where at least one file yields no reliable package fact (missing/unparseable package declaration, absent build metadata for Kotlin) while other files share packages; unknownPackageFiles.size > 0 fires the warning and adds every parsed file to incompleteFiles.

Common situations: Generated or template Java sources without package lines, partially checked-out monorepos where pom.xml/build.gradle facts are excluded by .gitnexusignore, Kotlin workspaces lacking build files, or files with BOM/encoding damage that breaks package-declaration detection.

Related errors

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