wiki: non-web projects produce near-empty output despite rich library structure

[mimosel]

Summary

Running npx codesight --wiki on a TypeScript project without HTTP routes or ORM models produces a
near-empty wiki, even though codesight's own scanner detects a large, richly structured codebase. The
wiki generator appears to be heavily biased towards web-app concepts (routes, models, components,
middleware, database, auth) and has no fallback strategy for library-heavy projects such as game
engines, CLI tools, data pipelines, or monorepos.

Additionally, index.md contains a dead reference to an article (database.md) that is never
generated on this project.

Environment

• codesight: 1.10.0 (latest on npm as of 2026-04-11, npx codesight)
• Node: v22.15.0
• OS: Windows 11
• Project: TypeScript game engine (~459 source files, PixiJS + React UI layer, no HTTP server, no ORM)

Steps to Reproduce

1. On a TypeScript project with:
   • 0 HTTP routes,
   • 0 ORM models,
   • ~130 library files under src/engine/, src/renderer/, src/types/, etc.,
   • a small React UI layer (~38 components),
2. run npx codesight --wiki.
3. Inspect .codesight/wiki/.

Expected Behavior

For a project where the main complexity lives in library code rather than in HTTP routes or ORM
schemas, the wiki should reflect the actual domain structure. A reasonable expectation:

• Domain articles grouped by top-level source directory (e.g. engine.md, renderer.md, types.md),
  or by import-graph clustering.
• At minimum, a generic libraries.md article analogous to the existing ui.md, listing libraries
  with their exported function signatures (the same data that already appears in CODESIGHT.md).
• No dead links in the index template.

Actual Behavior

1. Only two articles are generated on a codebase with 131 libraries

CLI output from the run:

Routes: 0
Models: 0
Components: 38
Libraries: 131
Env vars: 1
Middleware: 1
Import links: 1014
Hot files: 20

Generating wiki... .codesight/wiki/ (2 articles, ~1.563 tokens total)
Articles: overview.md, ui.md

Generated wiki files:

.codesight/wiki/
├── index.md (1.9 kB — navigation shell)
├── log.md (238 B — run log)
├── overview.md (956 B — scale, high-impact files, env vars)
└── ui.md (3.5 kB — 38 React components with props)

The 131 library files are completely absent from the wiki, even though codesight's own scanner
detects them and writes them to CODESIGHT.md (45 kB, ~12.800 tokens) with full function signatures.
The wiki output is ~1.563 tokens for a codebase whose full context map is ~12.800 tokens — roughly 12%
coverage.

For comparison, the project's real structural weight lives in files like:

src/engine/world.ts — imported by 114 files
src/engine/rng.ts — imported by 65 files
src/engine/grid-utils.ts — imported by 58 files
src/engine/game-engine.ts — imported by 38 files
src/engine/occupancy.ts — imported by 38 files
src/engine/sound-system.ts — imported by 39 files

None of these are reflected in a wiki article. overview.md mentions them in a short "High-Impact
Files" list but offers no structural overview of what src/engine/ contains or how it's organised.

2. Dead link in the index template

.codesight/wiki/index.md contains this line verbatim in its "How to Use" section:

• Database question: read database.md, then read the actual schema files

database.md does not exist in the generated output, because the project has no ORM models. The
template hardcodes references to articles that are only conditionally produced. This is misleading for
anyone following the index — either the reference should be removed when the article is absent, or a
stub should be generated.

3. Root cause (hypothesis)

From the pattern it looks like the wiki-generator emits articles binary-conditionally:

if (routes.length > 0) createArticle('routes.md')
if (models.length > 0) createArticle('database.md')
if (components.length > 0) createArticle('ui.md')
if (middleware.length > 0) createArticle('middleware.md')
// else nothing

There is no fallback branch for library code when the web-app concepts are absent or sparse. For
classes of projects where the interesting structure is library code, the wiki is therefore near-empty
regardless of actual project size.

Suggested Fix

In order of effort:

1. Small fix — remove dead links. Make the "How to Use" section in index.md dynamic: only
   mention articles that were actually generated for this project.

2. Medium fix — add a library-cluster fallback. When libraries.length > N (e.g. 20+), emit
   articles clustered by top-level source directory: engine.md, renderer.md, etc. Reuse the
   function-signature data that CODESIGHT.md already contains.

3. Larger fix — make the wiki strategy configurable. Add a --wiki-strategy flag (or
   codesight.config.json field):

   • web (current default)
   • library (dir-clustered domain articles)
   • auto (detect sparse web concepts → fall back to library mode)

Impact

Non-web TypeScript/JavaScript projects — game engines, CLI tools, library monorepos, data pipelines —
currently get near-empty wikis despite being structurally rich. The wiki's main stated value ("session
start: read index.md for orientation, ~200 tokens") falls flat on this class of projects, because
the index points to only two thin articles. Users fall back to reading CODESIGHT.md in full,
defeating the token-savings rationale of having a layered wiki in the first place.

Thanks for the tool.