scan-codebase

Name: scan-codebase
Author: Borda

23stars3forks

How to install scan-codebase?

borda/ai-rig/scan-codebase

$npx -y skills add Borda/AI-Rig --skill scan-codebase

Installs into the current project.

Summary

Scan the Python codebase and build a structural JSON index (import graph + blast-radius metrics). TRIGGER when: user asks to build, refresh, or rebuild the codemap index; user mentions stale index, missing symbols, or re-indexing after significant project changes; phrases: \"buil

Files · 1

View on GitHub

SKILL.md

1	<objective>
2
3	Python only — uses `ast.parse` to extract import graph + symbol metadata across all `.py` files; non-Python files not indexed. Writes `.cache/codemap/<project>.json`. No external deps. Zero-Python project (no `.py` files): index writes but empty — downstream queries return no results.
4
5	Index captures per module: import graph, blast-radius metrics, symbol list (classes, functions, methods with line ranges). Symbol data enables `scan-query symbol` / `find-symbol` to return target function source instead of full file reads.
6
7	Agents + develop skills query index via `scan-query` for module deps, blast radius, coupling, symbol source before editing.
8
9	NOT for: querying existing index (use `/codemap:query-code`); integration health checks or injection (use `/codemap:integration`); first-time codemap onboarding or injection into skill files (use `/codemap:integration init`).
10
11	</objective>
12
13	<workflow>
14
15	## Step 1: Run the scanner
16
17	Parse `$ARGUMENTS` to build invocation. Pass `--root <path>` if provided; pass `--incremental` if provided. Construct args conditionally — never pass literal placeholder strings:
18
19	Unsupported flag check — scan `$ARGUMENTS` for `--` prefixed tokens other than `--root` and `--incremental`. If any remain: print `! Unknown flag(s): \`--<token>\`. Supported: \`--root\`, \`--incremental\`.` then exit 1 — do not invoke AskUserQuestion (disable-model-invocation:true makes AskUserQuestion structurally unreachable). Run this check BEFORE invoking `parse_scan_args.py`.
20
21	```bash
22	# timeout: 10000
23	export CSID="${CLAUDE_CODE_SESSION_ID:-$PPID}"
24	_ARGS_UNSUPPORTED=0; _SKIP_NEXT=0
25	# unquoted $ARGUMENTS word-splits; parse_scan_args.py handles quoted paths
26	for _FLAG in $ARGUMENTS; do
27	[ "$_SKIP_NEXT" -eq 1 ] && { _SKIP_NEXT=0; continue; }
28	case "$_FLAG" in
29	--root) _SKIP_NEXT=1 ;;
30	--incremental) ;;
31	--*) printf "! Unsupported flag: %s\nSupported: --root <path>, --incremental\n" "$_FLAG" >&2; _ARGS_UNSUPPORTED=1 ;;
32	esac
33	done
34	[ "$_ARGS_UNSUPPORTED" -eq 0 ] \|\| exit 1
35	SETUP_STDERR="${TMPDIR:-/tmp}/codemap-setup-err-$$-${CSID}"
36	SCAN_STATE_FILE=$(bash "${CLAUDE_PLUGIN_ROOT:-plugins/codemap}/bin/setup_scan_env.sh" --arguments "$ARGUMENTS" 2>"$SETUP_STDERR")
37	if [ $? -ne 0 ] \|\| [ -z "$SCAN_STATE_FILE" ]; then
38	printf "! setup_scan_env.sh failed"; [ -s "$SETUP_STDERR" ] && printf ": %s" "$(cat "$SETUP_STDERR")"; printf "\n"; exit 1
39	fi
40	printf '%s' "$SCAN_STATE_FILE" > "${TMPDIR:-/tmp}/codemap-state-ref-${CSID}" # subsequent blocks read without knowing PID
41	```
42
43	```bash
44	# timeout: 360000
45	export CSID="${CLAUDE_CODE_SESSION_ID:-$PPID}"
46	SCAN_STATE_FILE=$(cat "${TMPDIR:-/tmp}/codemap-state-ref-${CSID}" 2>/dev/null)
47	[ -n "$SCAN_STATE_FILE" ] && [ -f "$SCAN_STATE_FILE" ] \|\| { printf "! codemap state missing — re-run from the beginning\n"; exit 1; }
48	# shellcheck source=/dev/null
49	. "$SCAN_STATE_FILE"
50	# NUL-delimited args file avoids eval; produced by parse_scan_args.py
51	_ARGS_FILE="${TMPDIR:-/tmp}/codemap-scan-args-nul-$$-${CSID}"
52	python3 "${CLAUDE_PLUGIN_ROOT:-plugins/codemap}/bin/parse_scan_args.py" "$SCAN_ARGS_RAW" --nul-output "$_ARGS_FILE"
53	SCAN_ARGS=()
54	while IFS= read -r -d '' _arg; do
55	SCAN_ARGS+=("$_arg")
56	done < "$_ARGS_FILE"
57	rm -f "$_ARGS_FILE"
58	if ! "$SCAN_BIN" --timeout 360 "${SCAN_ARGS[@]}"; then
59	printf "! scan-index failed (exit %d) — index may be stale or incomplete\n" "$?"
60	# remove sentinel on failure; stale sentinel misleads Step 2
61	rm -f "${TMPDIR:-/tmp}/codemap-incremental-noop-${PROJ_SLUG}-${CSID}"
62	exit 1
63	fi
64	```
65
66	`--root` naming note: when `--root <path>` given, index named after `basename(<path>)` — differs from default project index (uses git root's basename). Prior queries/edits against default index: `--root` index separate, queries won't see it unless same `--root` used consistently. Run `resolve_index_env.py` to verify index path after custom-root scan.
67
68	Scanner writes to `<root>/.cache/codemap/<project>.json` (or `$CODEMAP_INDEX_DIR/<project>.json` when set) and prints summary line:
69
70	```text
71	[codemap] ✓ .cache/codemap/<project>.json
72	[codemap] N modules indexed, M degraded
73	```
74
75	## Step 2: Report
76
77	After scan, read index and report compact summary:
78
79	```bash
80	# timeout: 15000
81	export CSID="${CLAUDE_CODE_SESSION_ID:-$PPID}"
82	# only report if index exists; Step 1 may have failed
83	SCAN_STATE_FILE=$(cat "${TMPDIR:-/tmp}/codemap-state-ref-${CSID}" 2>/dev/null)
84	[ -n "$SCAN_STATE_FILE" ] && [ -f "$SCAN_STATE_FILE" ] \|\| { printf "! codemap st

People who liked this also viewed

6 picks

Type

scan-codebase

23stars3forks

View on GitHub

How to install scan-codebase?

borda/ai-rig/scan-codebase

$npx -y skills add Borda/AI-Rig --skill scan-codebase

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	<objective>
2
3	Python only — uses `ast.parse` to extract import graph + symbol metadata across all `.py` files; non-Python files not indexed. Writes `.cache/codemap/<project>.json`. No external deps. Zero-Python project (no `.py` files): index writes but empty — downstream queries return no results.
4
5	Index captures per module: import graph, blast-radius metrics, symbol list (classes, functions, methods with line ranges). Symbol data enables `scan-query symbol` / `find-symbol` to return target function source instead of full file reads.
6
7	Agents + develop skills query index via `scan-query` for module deps, blast radius, coupling, symbol source before editing.
8
9	NOT for: querying existing index (use `/codemap:query-code`); integration health checks or injection (use `/codemap:integration`); first-time codemap onboarding or injection into skill files (use `/codemap:integration init`).
10
11	</objective>
12
13	<workflow>
14
15	## Step 1: Run the scanner
16
17	Parse `$ARGUMENTS` to build invocation. Pass `--root <path>` if provided; pass `--incremental` if provided. Construct args conditionally — never pass literal placeholder strings:
18
19	Unsupported flag check — scan `$ARGUMENTS` for `--` prefixed tokens other than `--root` and `--incremental`. If any remain: print `! Unknown flag(s): \`--<token>\`. Supported: \`--root\`, \`--incremental\`.` then exit 1 — do not invoke AskUserQuestion (disable-model-invocation:true makes AskUserQuestion structurally unreachable). Run this check BEFORE invoking `parse_scan_args.py`.
20
21	```bash
22	# timeout: 10000
23	export CSID="${CLAUDE_CODE_SESSION_ID:-$PPID}"
24	_ARGS_UNSUPPORTED=0; _SKIP_NEXT=0
25	# unquoted $ARGUMENTS word-splits; parse_scan_args.py handles quoted paths
26	for _FLAG in $ARGUMENTS; do
27	[ "$_SKIP_NEXT" -eq 1 ] && { _SKIP_NEXT=0; continue; }
28	case "$_FLAG" in
29	--root) _SKIP_NEXT=1 ;;
30	--incremental) ;;
31	--*) printf "! Unsupported flag: %s\nSupported: --root <path>, --incremental\n" "$_FLAG" >&2; _ARGS_UNSUPPORTED=1 ;;
32	esac
33	done
34	[ "$_ARGS_UNSUPPORTED" -eq 0 ] \|\| exit 1
35	SETUP_STDERR="${TMPDIR:-/tmp}/codemap-setup-err-$$-${CSID}"
36	SCAN_STATE_FILE=$(bash "${CLAUDE_PLUGIN_ROOT:-plugins/codemap}/bin/setup_scan_env.sh" --arguments "$ARGUMENTS" 2>"$SETUP_STDERR")
37	if [ $? -ne 0 ] \|\| [ -z "$SCAN_STATE_FILE" ]; then
38	printf "! setup_scan_env.sh failed"; [ -s "$SETUP_STDERR" ] && printf ": %s" "$(cat "$SETUP_STDERR")"; printf "\n"; exit 1
39	fi
40	printf '%s' "$SCAN_STATE_FILE" > "${TMPDIR:-/tmp}/codemap-state-ref-${CSID}" # subsequent blocks read without knowing PID
41	```
42
43	```bash
44	# timeout: 360000
45	export CSID="${CLAUDE_CODE_SESSION_ID:-$PPID}"
46	SCAN_STATE_FILE=$(cat "${TMPDIR:-/tmp}/codemap-state-ref-${CSID}" 2>/dev/null)
47	[ -n "$SCAN_STATE_FILE" ] && [ -f "$SCAN_STATE_FILE" ] \|\| { printf "! codemap state missing — re-run from the beginning\n"; exit 1; }
48	# shellcheck source=/dev/null
49	. "$SCAN_STATE_FILE"
50	# NUL-delimited args file avoids eval; produced by parse_scan_args.py
51	_ARGS_FILE="${TMPDIR:-/tmp}/codemap-scan-args-nul-$$-${CSID}"
52	python3 "${CLAUDE_PLUGIN_ROOT:-plugins/codemap}/bin/parse_scan_args.py" "$SCAN_ARGS_RAW" --nul-output "$_ARGS_FILE"
53	SCAN_ARGS=()
54	while IFS= read -r -d '' _arg; do
55	SCAN_ARGS+=("$_arg")
56	done < "$_ARGS_FILE"
57	rm -f "$_ARGS_FILE"
58	if ! "$SCAN_BIN" --timeout 360 "${SCAN_ARGS[@]}"; then
59	printf "! scan-index failed (exit %d) — index may be stale or incomplete\n" "$?"
60	# remove sentinel on failure; stale sentinel misleads Step 2
61	rm -f "${TMPDIR:-/tmp}/codemap-incremental-noop-${PROJ_SLUG}-${CSID}"
62	exit 1
63	fi
64	```
65
66	`--root` naming note: when `--root <path>` given, index named after `basename(<path>)` — differs from default project index (uses git root's basename). Prior queries/edits against default index: `--root` index separate, queries won't see it unless same `--root` used consistently. Run `resolve_index_env.py` to verify index path after custom-root scan.
67
68	Scanner writes to `<root>/.cache/codemap/<project>.json` (or `$CODEMAP_INDEX_DIR/<project>.json` when set) and prints summary line:
69
70	```text
71	[codemap] ✓ .cache/codemap/<project>.json
72	[codemap] N modules indexed, M degraded
73	```
74
75	## Step 2: Report
76
77	After scan, read index and report compact summary:
78
79	```bash
80	# timeout: 15000
81	export CSID="${CLAUDE_CODE_SESSION_ID:-$PPID}"
82	# only report if index exists; Step 1 may have failed
83	SCAN_STATE_FILE=$(cat "${TMPDIR:-/tmp}/codemap-state-ref-${CSID}" 2>/dev/null)
84	[ -n "$SCAN_STATE_FILE" ] && [ -f "$SCAN_STATE_FILE" ] \|\| { printf "! codemap st

People who liked this also viewed

6 picks

Type