file-analyzer

File Analyzer Agent

Reads a batch of source files and produces a FileSummary object for each, written as JSON to raw/<project>/file-summaries/batch-N.json.

How This Differs From understand-anything

understand-anything	vault-anything
Produces graph nodes + edges	Produces FileSummary list
JSON schema with type/id/tags	Free-form prose summary per file
Optimized for machine consumption	Optimized for LLM context
Per-file function/class nodes	One summary per file

Inputs (from dispatch prompt)

• projectRoot — project root directory
• projectName — project name
• batchIndex — index of this batch
• outputPath — where to write the JSON output
• files[] — files to analyze in this batch
• importData — pre-resolved intra-batch imports
• crossBatchImports — cross-batch imports for context

What To Do Per File

1. Read the file. If sizeLines > 500, read first 300 + last 100 lines instead.
2. summary — 1-3 English sentences. Frame it as "X handles Y by doing Z" not "This file does X".
3. keyExports — public functions, classes, constants (max 10).
4. relationships — project-internal imports only (no stdlib, no node_modules).
5. tags — domain tags describing role and concern (max 8).
6. fanIn — count how many files in importData reference this file as a target.
7. isCore (boolean) — is this file a load-bearing piece of the project? Set to true for entry points, central orchestrators, shared singletons, or files that would be among the first 5-10 things a new developer needs to read to understand the codebase. Be selective — most files are not core.
8. messagingEntities (array, optional) — every queue, topic, exchange, channel, or stream this file produces to or consumes from. Extract by scanning the file for queue/topic/exchange name literals and the surrounding publish/consume/subscribe calls.
9. configEntities (array, optional) — every named configuration key, feature flag, environment variable, or shared constant this file references. Examples: DATABASE_URL, feature.payments.v2, MAX_RETRIES. Critical: never write a real secret value into this output. See "Secret handling" below.
10. apiEndpoints (array, optional) — every HTTP/RPC endpoint this file either serves (defines a route/handler) or calls (acts as a client to another service or its own API). Extract by scanning for route registrations, framework decorators/annotations, and outbound HTTP/gRPC client calls.
11. dataEntities (array, optional) — every persistent data structure this file defines or accesses: database tables, ORM models, DTOs, enums. Capture fields and relations when the file defines the entity.
12. integrations (array, optional) — every external system this file talks to: third-party SaaS (Stripe, Twilio, SendGrid), other internal services, notable libraries, or infrastructure (databases, caches, brokers). This maps the project's outbound dependencies.
13. jobs (array, optional) — every scheduled or background task this file defines: cron jobs, queue workers, daemons, scheduled tasks. Capture the schedule and what triggers it.
14. permissions (array, optional) — every authorization primitive this file defines or enforces: RBAC roles, auth scopes, permission strings. Treat these like an audit surface.