feat(orient): 10-second codebase orientation brief (closes #160)

[Wolfvin]

What

Adds a new codelens orient command that produces a 10-second structured codebase orientation brief. It answers the first four questions a developer asks when entering an unfamiliar repo:

1. What framework/stack is this? — framework_db.detect_frameworks_brief()
2. How do I run, build, and test it? — manifest_parser.extract_commands()
3. Where do I start reading? — file_ranker.rank_start_here_files()
4. What CI/Docker infrastructure exists? — inline detection in commands/orient.py

Pure-filesystem: no subprocess, no network, no LSP. Reads manifest files + walks the source tree once.

Why

CodeLens is a deep-analysis tool (taint, callgraph, secrets, dead-code). There is currently no command that answers the first questions a developer asks when entering an unfamiliar repo. Issue #160 asks for a zero-setup, pure-static "repo orientation brief" ported from codeglance (TypeScript, MIT — logic ported, no code copied).

Files touched

New files (6):

• scripts/commands/orient.py — command module + entry-point/CI/Docker detection + output rendering (text/json/compact)
• scripts/orient_lib/__init__.py — analyzer sub-package marker
• scripts/orient_lib/framework_db.py — data-driven framework lookup table (5 ecosystems, 60+ frameworks)
• scripts/orient_lib/manifest_parser.py — run/build/test command extraction from package.json, Makefile, pyproject.toml, Cargo.toml, go.mod, pom.xml/build.gradle
• scripts/orient_lib/file_ranker.py — Start Here scoring logic (filename/depth/line-count/directory-context)
• tests/test_orient.py — 31 tests covering all 5 sub-features + output schema + compact rendering

Modified files (7):

• scripts/codelens.py — add "orient" to the skip-global-format command list (same pattern as doctor/sessions, 2-line change at L1289 + L1291)
• README.md, SKILL.md, SKILL-QUICK.md, pyproject.toml, skill.json, scripts/graph_model.py — command count sync 70 → 71 (auto-generated by python3 scripts/sync_command_count.py --apply)

Architecture deviation from issue spec

Issue #160 specifies scripts/orient/framework_db.py etc. I named the package scripts/orient_lib/ instead of scripts/orient/ to avoid a Python import collision: commands/orient.py and a top-level orient/ package both claim the orient module name, triggering a circular import (cannot import name 'detect_frameworks_brief' from partially initialized module 'orient'). The orient_lib name sidesteps this without touching the command name. Documented in scripts/orient_lib/__init__.py docstring.

Definition of Done checklist

• codelens orient . produces structured output for Node.js, Python, and Go repos (verified via fixture tests + manual run on CodeLens itself)
• --format json (default), --format compact (single-line ≤300 tokens), --format text (human-readable) all work
• Framework detection covers: Next.js, React, Express, FastAPI, Django, Flask, Gin, Axum, Spring Boot (+ 50+ more across 5 ecosystems)
• Start Here ranking returns ≤8 files, skips tests/generated/migrations
• CI/Docker detection reads from filesystem only (no subprocess)
• sync_command_count.py --apply run after registration (70 → 71)
• File headers (@WHO, @WHAT, @PART, @ENTRY) on all new files
• @FLOW: ORIENT, @CALLS, @MUTATES on entry function cmd_orient()

Verification

pytest tests/test_orient.py -v — 31 tests, all pass

tests/test_orient.py ...............................  [100%]
============================== 31 passed in 0.56s ==============================

Test classes:

• TestFrameworkDetection (4) — Node.js/Python/Go/unknown ecosystem
• TestCommandExtraction (3) — npm scripts / pytest+ruff / go standard
• TestEntryPointDetection (4) — per-ecosystem + max-8 cap
• TestStartHereRanking (5) — top-N, skip tests/migrations, integer scores
• TestInfraDetection (8) — CI/Docker/env/test-framework/linter
• TestOutputSchema (6) — all top-level + nested block shapes
• TestCompactFormat (1) — single-line rendering

Full test suite regression — 1405 passed, 76 skipped, 1 pre-existing failure

1 failed, 1405 passed, 76 skipped in 61.20s

The 1 failure (tests/test_codelensignore.py::TestBackwardCompat::test_actual_target_dir_is_ignored) is pre-existing — verified by checking out main and running the same test: it fails identically. Unrelated to this PR.

Manual test: codelens orient . on CodeLens itself

$ python3 scripts/codelens.py orient . --format compact
Python/no primary framework | pytest(test); ruff check .(lint) | CI/no-Docker/no-.env | start: setup.sh, scripts/commands/init.py, scripts/security/config_secret_redaction.py

$ python3 scripts/codelens.py orient . --format text
== Codebase Orientation: /home/z/my-project/repos/CodeLens ==

Framework: Python / None
  Summary: Python project (no recognized frameworks)

Commands:
  [test] pytest — pytest test runner (detected in pyproject.toml)
  [lint] ruff check . — ruff linter (detected in pyproject.toml)

Start here (top files to read first):
  [ 41] setup.sh — filename=setup, shallow depth, 205 lines
  [ 36] scripts/commands/init.py — filename=init, 74 lines
  [ 33] scripts/security/config_secret_redaction.py — filename=config_secret_redaction, 555 lines
  ...

Infrastructure:
  CI: True (5 file(s))
  Docker: False
  .env file: False
  Test framework: None
  Linter: None

CodeLens itself has no Python web framework (correct — it's a CLI tool), so primary=None and ecosystem=Python is the right answer. CI detection finds the 5 workflow files in .github/workflows/.

Fixture tests on 3 ecosystems (from tests/test_orient.py)

Ecosystem	Fixture	Primary	Secondary	Test framework	Linter
Node.js	Next.js + React + Prisma + Jest + Tailwind	Next.js	React, Prisma, TailwindCSS, Jest, ESLint	jest	eslint
Python	FastAPI + SQLAlchemy + pytest + ruff	FastAPI	SQLAlchemy	pytest	ruff
Go	Gin + GORM	Gin	GORM	go test	—

Issue link

Closes #160 — #160

Findings

• scripts/orient/ → scripts/orient_lib/ rename. Issue [FEAT] codelens orient — 10-second codebase orientation brief #160 spec asks for scripts/orient/framework_db.py etc. A top-level orient/ package collides with commands/orient.py at import time (both claim the orient module name → circular import). Renamed to orient_lib/ and documented the reason in the package docstring. If the maintainers prefer the spec name, the alternative is to rename the command module (e.g., commands/orient_cmd.py registering as orient) — but that breaks the commands/<name>.py convention.
• test_framework / linter detection is config-file-based, not dependency-based. For example, a Node.js project with jest in devDependencies but no jest.config.js will report test_framework: None. This matches codeglance's behavior (config files are the source of truth) and keeps the detector filesystem-only. If dependency-based detection is desired later, it would be a follow-up enhancement.
• file_set_hash for Start Here is not stable across runs because os.walk directory order is not guaranteed. The scores are stable (deterministic per file), but the order of files with equal scores may vary. For the orient use case (top-N recommendation) this is acceptable — all tied files are equally good starting points.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud