Egonex-AI/Understand-Anything · error · Error

Invalid input: requires { projectRoot: string, sourceFilePat

Error message

Invalid input: requires { projectRoot: string, sourceFilePaths: string[], gitCommitHash: string }

What it means

Thrown by build-fingerprints.mjs main() after JSON.parse-ing its input file. It validates that the input object has projectRoot (truthy), sourceFilePaths (an Array), and gitCommitHash (typeof string). Missing or wrong-typed any of the three aborts before constructing the tree-sitter plugin, since fingerprints are meaningless without a known commit and file set.

Source

Thrown at understand-anything-plugin/skills/understand/build-fingerprints.mjs:70

  builtinLanguageConfigs,
  registerAllParsers,
  buildFingerprintStore,
  saveFingerprints,
} = core;

async function main() {
  const [, , inputPath] = process.argv;
  if (!inputPath) {
    process.stderr.write('Usage: node build-fingerprints.mjs <input.json>\n');
    process.exit(1);
  }

  const { projectRoot, sourceFilePaths, gitCommitHash } = JSON.parse(
    readFileSync(inputPath, 'utf-8'),
  );

  if (!projectRoot || !Array.isArray(sourceFilePaths) || typeof gitCommitHash !== 'string') {
    throw new Error(
      'Invalid input: requires { projectRoot: string, sourceFilePaths: string[], gitCommitHash: string }',
    );
  }

  // Create tree-sitter plugin with all configs that have WASM grammars,
  // mirroring extract-structure.mjs so the baseline matches the comparison
  // logic used during auto-updates.
  const tsConfigs = builtinLanguageConfigs.filter((c) => c.treeSitter);
  const tsPlugin = new TreeSitterPlugin(tsConfigs);
  await tsPlugin.init();

  const registry = new PluginRegistry();
  registry.register(tsPlugin);
  registerAllParsers(registry);

  const store = buildFingerprintStore(projectRoot, sourceFilePaths, registry, gitCommitHash);
  saveFingerprints(projectRoot, store);

View on GitHub (pinned to 32944829e7)

Solutions

Inspect the input JSON at the inputPath argument: confirm it has projectRoot (non-empty string), sourceFilePaths (array of strings), and gitCommitHash (string).
If gitCommitHash is missing, ensure the repo is a git checkout with at least one commit before regenerating the input.
Update the producer (the agent/script that writes this input) to use the exact field names projectRoot, sourceFilePaths, gitCommitHash.
Wrap a single file in an array: pass ["./src/a.ts"] not "./src/a.ts" for sourceFilePaths.

Example fix

// before — wrong field names / scalar instead of array
{ "root": "./repo", "files": "./src/a.ts", "commit": "abc123" }

// after — exact schema
{ "projectRoot": "./repo", "sourceFilePaths": ["./src/a.ts"], "gitCommitHash": "abc123" }

Defensive patterns

Strategy: validation

Validate before calling

import { readFileSync } from 'node:fs';
function readFingerprintInput(inputPath) {
  const raw = JSON.parse(readFileSync(inputPath, 'utf-8'));
  if (!raw.projectRoot) throw new Error('input missing projectRoot');
  if (!Array.isArray(raw.sourceFilePaths)) throw new Error('sourceFilePaths must be an array');
  if (typeof raw.gitCommitHash !== 'string') throw new Error('gitCommitHash must be a string');
  return raw;
}

Type guard

function isFingerprintInput(v) {
  return v !== null && typeof v === 'object'
    && typeof v.projectRoot === 'string' && v.projectRoot.length > 0
    && Array.isArray(v.sourceFilePaths)
    && v.sourceFilePaths.every((f) => typeof f === 'string')
    && typeof v.gitCommitHash === 'string';
}

Try / catch

try {
  const input = readFingerprintInput(inputPath);
  // ... proceed
} catch (e) {
  process.stderr.write(`build-fingerprints input invalid: ${e.message}\n`);
  process.exit(1);
}

Prevention

Producers must emit exactly projectRoot, sourceFilePaths (array), gitCommitHash (string).
Ensure the repo has at least one git commit before fingerprinting.
Wrap single files in an array rather than passing a scalar.

When it happens

Trigger: process.argv[3] (inputPath) is missing — but that hits the earlier usage/exit(1) branch. This specific throw fires when the JSON file parsed fine but lacks projectRoot, has sourceFilePaths that is not an array (e.g. an object or string), or gitCommitHash is not a string (e.g. undefined, number).

Common situations: The caller (project-scanner agent / fingerprint driver) wrote an input JSON with a field typo (sourceFilePaths vs filePaths, commit vs gitCommitHash). sourceFilePaths was passed as a single string rather than an array. The repo has no git commit (detached/empty) so gitCommitHash came back undefined. An old input format predating the schema.

Related errors

AI-assisted analysis of Egonex-AI/Understand-Anything@32944829e7 (2026-08-12). Data as JSON: /api/errors/068c8eceb532968a. Report an issue: GitHub.