Index format

Reading stacklit.json

Project and tech

{
  "project": { "name": "my-app", "type": "monorepo" },
  "tech": {
    "primary_language": "typescript",
    "languages": { "typescript": { "files": 120, "lines": 14000 } },
    "frameworks": ["React", "Express"]
  },
  "structure": {
    "entrypoints": ["src/index.ts"],
    "total_files": 120,
    "total_lines": 14000
  }
}

tech.framework_patterns adds detected routes, API, middleware and entry locations for known frameworks. merkle_hash is the content hash used by stacklit diff and the git hook to skip needless regeneration.

Modules

Each module is a directory of related source files:

"src/auth": {
  "purpose": "Authentication and authorization",
  "language": "typescript",
  "files": 8,
  "lines": 1200,
  "file_list": ["service.ts", "middleware.ts", "types.ts"],
  "exports": ["AuthProvider", "useSession()", "loginAction(email, password)"],
  "type_defs": { "AuthState": "user User, token string, isLoading boolean" },
  "depends_on": ["src/db", "src/config"],
  "depended_by": ["src/api", "src/middleware"],
  "activity": "high"
}

• purpose: derived from the directory name and a built-in vocabulary, so it is generic (for example “Json” for a json directory). It is not a semantic summary.
• exports: public functions, classes and types with signatures where the language provides them, capped by max_exports.
• type_defs: field definitions of key structs, interfaces and classes.
• depends_on / depended_by: module-level graph built from import statements. Entries are sometimes shortened to the last path segment.
• activity: high, medium or low from 90-day git commit frequency.

Dependencies

"dependencies": {
  "edges": [["src/api", "src/auth"], ["src/auth", "src/db"]],
  "most_depended": ["src/db", "src/config"],
  "isolated": ["scripts"]
}

most_depended ranks modules by number of dependents. isolated lists modules with no edges in or out.

Git and hints

"git": { "hot_files": [{ "path": "src/api/routes.ts", "commits_90d": 14 }] },
"hints": {
  "add_feature": "Add handler in src/api, register in src/index.ts",
  "test_command": "npm test",
  "env_vars": ["DATABASE_URL", "JWT_SECRET"],
  "do_not_touch": ["migrations/", ".github/"]
}

env_vars holds names found in os.Getenv, process.env and os.environ style accesses. Values are never read. Hints are heuristics: the test command comes from well-known build files and the add-feature hint from module names such as api or handler.

Monorepo support

Workspaces are detected automatically and appear as module groups in the index.

Polyrepo scanning

Scan several separate repositories at once:

echo "/path/to/repo-a" > repos.txt
echo "/path/to/repo-b" >> repos.txt
stacklit init --multi repos.txt

Blank lines and # comments in the file are skipped. The result is stacklit-multi.json in the current directory, with module data for each repo and combined totals. Cross-repo dependency edges are not computed; that is on the roadmap.

Generated from docs/USAGE.md in the repository, the single source of truth.