archeious/luminos
1
0
Fork 0
Code Issues 42 Pull requests Projects 1 Releases Packages Wiki Activity Actions
luminos/CLAUDE.md
Jeff Smith a6333858ee test(ai): add unit coverage for pure helpers in ai.py (#55) 
ai.py was documented as fully exempt from unit testing because the dir
loop and synthesis pass require a live Anthropic API. But several
helpers in the module are pure functions with no API dependency, and
they're the kind of thing that breaks silently. The #57 refactor added
two more (_build_dir_loop_context, _flush_partial_dir_entry) that are
also naturally testable.

New tests/test_ai_pure.py — 45 tests across 8 helpers:

- _should_skip_dir: exact-match, *.egg-info glob, no-match cases
- _path_is_safe: inside, nested, equals, outside, traversal,
  sibling-with-target-prefix (the easy-to-miss security case)
- _default_survey: shape, zero confidence guarantees no filtering,
  passes through _filter_dir_tools unchanged
- _format_survey_block: None, empty, minimal, with relevant_tools,
  with skip_tools, with domain_notes, empty-list omission
- _filter_dir_tools: None, empty, low confidence, high confidence
  filters, protected tools never removed, unknown skip silently
  ignored, garbage/None confidence treated as zero, threshold
  boundary inclusive
- _format_survey_signals: None, empty, zero total_files, full,
  partial (only extensions)
- _block_to_dict: text, tool_use, unknown type
- _flush_partial_dir_entry (#57): idempotent when entry exists,
  no-file-entries stub path, with-file-entries summary synthesis,
  notable_files collection

Uses the same _make_manager() pattern as test_cache.py to construct
a _CacheManager rooted in a tempdir, sidestepping CACHE_ROOT entirely.

Doc updates:
- CLAUDE.md, README.md, docs/wiki/DevelopmentGuide.md: ai.py is no
  longer fully exempt — only the API-dependent loops are. Pure
  helpers are covered by test_ai_pure.py.

Verification: 209 tests pass (164 prior + 45 new).
2026-04-11 10:24:47 -06:00

5.1 KiB
Raw Blame History

CLAUDE.md

STOP. Before producing ANY output, pull docs/wiki/, fetch open Forgejo issues for archeious/luminos, and present them as suggested tasks. Then ask: "What's the one thing we're shipping?" No preamble. No acknowledgment. Just the suggested tasks and the question. Everything else comes after the user answers.

Current Project State

  • Phase: Active development — Phase 1 + 2 + 2.5 complete; Phase 3 (investigation planning) ready to start
  • Last worked on: 2026-04-11
  • Last commit: Merge pull request 'feat: AI investigation is the product, drop zero-dep constraint (#64)' (#65)
  • Blocking: None

Project Overview

Luminos is a file system intelligence tool. Point it at a directory and it runs a multi-pass agentic investigation via the Claude API: a survey pass, isolated dir-loop agents per directory, and a synthesis pass that produces a project-level verdict with severity-ranked flags. A lightweight base scan runs first to feed the agent its initial picture of the target.

Module Map

Module Purpose
luminos.py Entry point — arg parsing, scan(), main()
luminos_lib/ai.py Multi-pass agentic analysis via Claude API
luminos_lib/ast_parser.py tree-sitter code structure parsing
luminos_lib/cache.py Investigation cache management (incl. clear_cache)
luminos_lib/code.py Language detection, LOC counting
luminos_lib/disk.py Per-directory disk usage
luminos_lib/filetypes.py File classification (7 categories)
luminos_lib/prompts.py AI system prompt templates
luminos_lib/recency.py Recently modified files
luminos_lib/report.py Terminal report formatter
luminos_lib/tree.py Directory tree visualization

Details: wiki — Architecture | Development Guide

Key Constraints

  • AI investigation is the product. The base scan exists to feed the agent. There is no --ai flag and no --no-ai mode. AI runs unconditionally on every invocation.
  • Anthropic API key is required. If ANTHROPIC_API_KEY is unset, luminos exits cleanly (exit 0) with a one-line hint instead of running.
  • Dependencies installed via requirements.txt. anthropic, tree-sitter + grammars, and python-magic are normal pip dependencies, not lazy imports. setup_env.sh creates a venv and installs them.
  • Subprocess for OS tools. LOC counting, file detection, disk usage, and recency shell out to GNU coreutils. Do not reimplement in pure Python.
  • Graceful degradation everywhere. Permission denied, subprocess timeouts, individual dir-loop failures — all handled without crashing the run.

Running Luminos

# Activate the venv (one-time setup: ./setup_env.sh)
source ~/luminos-env/bin/activate
export ANTHROPIC_API_KEY=your-key-here

# Run an investigation
python3 luminos.py <target>

# Common flags
python3 luminos.py -d 8 -a -x .git -x node_modules <target>
python3 luminos.py --json -o report.json <target>
python3 luminos.py --fresh <target>
python3 luminos.py --clear-cache

Project-Specific Test Notes

Run tests with python3 -m unittest discover -s tests/. Modules exempt from unit testing: ast_parser.py (requires tree-sitter grammars at import time) and prompts.py (string templates only). ai.py is partially covered: end-to-end loops require a live Anthropic API and stay exempt, but the pure helpers (_filter_dir_tools, _format_survey_block, _path_is_safe, _should_skip_dir, _block_to_dict, _flush_partial_dir_entry, etc.) are covered by tests/test_ai_pure.py.

(Development workflow, branching discipline, and session protocols live in ~/.claude/CLAUDE.md.)

Naming Conventions

Context Convention Example
Functions / variables snake_case classify_files, dir_path
Classes PascalCase _TokenTracker, _CacheManager
Constants UPPER_SNAKE_CASE MAX_CONTEXT, CACHE_ROOT
Module files snake_case ast_parser.py
CLI flags kebab-case --clear-cache, --fresh
Private functions leading underscore _run_synthesis

Session Log

# Date Summary
6 2026-04-07 Extracted shared workflow/branching/protocols from project CLAUDE.md to global ~/.claude/CLAUDE.md; moved externalize.md and wrap-up.md to ~/.claude/protocols/
7 2026-04-07 Phase 1 audit — closed #1 (only #54 remains); gitea MCP credential overhaul: dedicated claude-code Forgejo user, admin on luminos, write+delete verified end-to-end
8 2026-04-07 Closed #54 — added confidence/confidence_reason to write_cache tool schema description; Phase 1 milestone now 4/4 complete
9 2026-04-11 Scope shift (#64): AI investigation is the product, zero-dep constraint dropped, watch mode + capabilities.py deleted, requirements.txt added, README/CLAUDE/PLAN/wiki rewritten

Full log: wiki — Session Retrospectives