@layrx/repository

Repository Indexing module for LayrX – discovers files, collects metadata, persists to SQLite, and produces indexing statistics.

Purpose

Scans a local repository recursively, skips configured ignore patterns, collects filesystem metadata (no file contents), stores results in SQLite, and returns aggregate statistics for the Local Agent.

Flow

indexRepository(path)
        │
        ▼
validateRepositoryPath()     ── invalid / not directory / permission denied → throw
        │
        ▼
RepositoryScanner.scan()     ── BFS walk, skip ignored dirs, lstat metadata only
        │
        ▼
RepositoryStatisticsCalculator.compute()
        │
        ▼
RepositoryMetadata.saveIndex() ── transaction: repositories + files tables
        │
        ▼
IndexResult { repository, statistics, ignoredFolders }

Architecture

| Module | Responsibility | |--------|----------------| | IgnoreMatcher | Name-based ignore rules (configurable) | | RepositoryScanner | Path validation and recursive metadata scan | | RepositoryStatisticsCalculator | Aggregate counts and file type breakdown | | RepositoryMetadata | SQLite persistence and queries | | RepositoryIndexer | Orchestrates the full indexing pipeline | | migrations/ | Versioned SQL schema (001_create_repository_tables.sql) |

Public API

import {
  indexRepository,
  getRepository,
  getFiles,
  getStatistics,
} from '@layrx/repository';

const result = await indexRepository('/path/to/repo');
console.log(result.statistics.totalFiles);

const repo = getRepository();
const files = getFiles();
const stats = getStatistics();

RepositoryIndexer class

Use when you need an isolated instance (custom DB path, ignore list, or logger):

const indexer = new RepositoryIndexer({
  databasePath: './data/layrx.db',
  ignorePatterns: ['node_modules', '.git'],
});
await indexer.index('./my-repo');
indexer.close();

Default ignore patterns

node_modules, .git, .next, dist, build, coverage, out, .cache, .vscode, .idea, .DS_Store

Override via ignorePatterns in options.

Database schema

See migration src/migrations/001_create_repository_tables.sql:

• repositories – one row per indexed repository root
• files – one row per file/directory entry (FK to repositories)

Dependencies

• @layrx/database – SQLite connection helper
• @layrx/logger – Pino structured logging
• @layrx/types – shared branded types
• @layrx/utils – path and timestamp helpers

Tests

npm run test --workspace=@layrx/repository

Covers: empty repo, invalid path, ignore folders, SQLite persistence, statistics, broken symlinks.

Future improvements

• .gitignore rule parsing (not just fixed name list)
• Incremental re-index on file watcher events
• Parallel directory reads for very large repositories
• Symbol extraction via @layrx/parser (Tree-sitter)
• Dependency graph generation (separate feature)