tools-stub-scan — IMP FORGE

Stub/debt-marker scanner. Finds hard stubs (todo!/unimplemented!) and structured debt markers (TODO/FIXME/HACK/STUB comments) across the tree, maintains a machine-generated section in docs/TECH-DEBT.md, and queues one GitHub issue per crate (deduplicated by title) so stubs become tracked work instead of silent rot.

Tier	tools
Role	unclassified (baselined)
Path	`crates/tools/stub-scan`
Edition	2021
Targets	tools-stub-scan, tools_stub_scan
Public items	20 across 1 module
Tests	9

What it is for

Stub / debt-marker scanner.

Two classes, both high-precision by construction:

hard-stub — todo!(...) / unimplemented!(...) in code. The

function exists, callers link against it, and it panics at runtime. String literals and comments never match (the source is lexed first).

marker — a structured debt comment: TODO / FIXME / HACK /

STUB as a whole word inside a // or /* */ comment. Only comments match — prose words like "placeholder" in doc text are deliberately NOT flagged (too noisy to act on).

The scanner's job is to turn these into tracked work: a machine-managed section in docs/TECH-DEBT.md (sentinel block, same convention as tools-update-process) and one GitHub issue per crate, deduplicated by title so re-runs never spam the tracker.

Sprint 4.21 adds the other half. Walking the tree is the SENSOR; store is the RECORD, so what the walk found becomes queryable alongside the crate rows the corpus already holds. Documents and issues are for people; neither can answer "which application-tier crates are still stubs?" without someone re-walking the tree by hand.

Capabilities

`crate root`

Stub / debt-marker scanner.

Item
`fn one_segment_crate_dirs(rel_files : & String) -> BTreeSet <String>`
`fn issue_title(crate_key : & str) -> String`
`pub const DEBT_BEGIN: & str`
`pub const DEBT_END: & str`
`fn splice_debt(existing : & str, section : & str) -> String`

`Finding`

Stub / debt-marker scanner.

Item
`pub struct Finding`
`fn scan_source(rel : & str, src : & str, out : & mut Vec <Finding>, one_segment_dirs : & BTreeSet <String>,)`
`fn scan(repo_root : & Path) -> Result <Vec <Finding>>`
`fn group_by_crate(findings : & Finding) -> BTreeMap <String, Vec <& Finding>>`
`fn issue_body(crate_key : & str, findings : & & Finding) -> String`
`fn render_debt_section(findings : & Finding) -> String`

`Kind`

Stub / debt-marker scanner.

Item
`pub enum Kind`
`Kind :: fn label(& self) -> & 'static str`

`store (other)`

The scanner's second capability: findings as data.

Item
`pub const STUB_SCAN_MIGRATIONS: & (& str, & str)`
`pub const MIGRATION_MODULE: & str`
`async fn migrate(pool : & PgPool) -> Result <u32>`
`async fn record(pool : & PgPool, findings : & Finding) -> Result <usize>`
`async fn count(pool : & PgPool) -> Result <usize>`
`async fn load(pool : & PgPool) -> Result <Vec <Finding>>`
`async fn hard_stubs_by_crate(pool : & PgPool) -> Result <Vec <(String, i64)>>`

How to use it

No examples/ target and no doctest in this crate's rustdoc. The tests listed under Verification are the closest executable usage.

Module structure

tools_stub_scan

store

Public surface

`crate root`

Item	What it is
`pub enum Kind`	Which class of stub a finding belongs to.
`Kind :: fn label(& self) -> & 'static str`	—
`pub struct Finding`	One stub site.
`fn one_segment_crate_dirs(rel_files : & String) -> BTreeSet <String>`	The one-segment crate-root set for `crate_key`: every dir directly under `crates/` that holds its own `Cargo.toml` (measured from the same file walk the scan reads — no registry to drift from the disk).
`fn scan_source(rel : & str, src : & str, out : & mut Vec <Finding>, one_segment_dirs : & BTreeSet <String>,)`	Scan one source file.
`fn scan(repo_root : & Path) -> Result <Vec <Finding>>`	Scan the tree rooted at `repo_root`.
`fn group_by_crate(findings : & Finding) -> BTreeMap <String, Vec <& Finding>>`	Group findings per crate for the issue queue and the debt section.
`fn issue_title(crate_key : & str) -> String`	The stable, deduplicatable issue title for a crate's stub queue.
`fn issue_body(crate_key : & str, findings : & & Finding) -> String`	The issue body for one crate group.
`pub const DEBT_BEGIN: & str`	—
`pub const DEBT_END: & str`	—
`fn render_debt_section(findings : & Finding) -> String`	Render the managed TECH-DEBT.md section.
`fn splice_debt(existing : & str, section : & str) -> String`	Splice the managed section into the TECH-DEBT.md content (replace the existing sentinel block, or append one).

`store`

Item	What it is
`pub const STUB_SCAN_MIGRATIONS: & (& str, & str)`	The schema this crate owns inside `corpus_sourcecode`, applied through the same module-migration ledger every other module uses.
`pub const MIGRATION_MODULE: & str`	The module name this crate's migrations are recorded under.
`async fn migrate(pool : & PgPool) -> Result <u32>`	Apply this crate's migrations
`async fn record(pool : & PgPool, findings : & Finding) -> Result <usize>`	Replace the recorded findings with this scan's, in one transaction
`async fn count(pool : & PgPool) -> Result <usize>`	How many findings the recorded snapshot holds
`async fn load(pool : & PgPool) -> Result <Vec <Finding>>`	Read the recorded snapshot back, without walking the tree
`async fn hard_stubs_by_crate(pool : & PgPool) -> Result <Vec <(String, i64)>>`	Findings per crate, straight from the database

No pub use re-exports: every item above is declared in this crate.

Boundary

Reaches into application.

Shares tier tools with 84 other crates: tools-advisory-reach, tools-archive-guard, tools-artifact-scaffold, tools-ask-ai-core, tools-ask-ais, tools-ask-gemini, tools-book, tools-book-report, … (84 total).

_What this crate deliberately does NOT own is a judgment. No committed registry records one for it, so none is stated here._

Where it sits

Tier (ontology)	`tools`
Architectural role (taxonomy)	`unclassified (baselined)`
Location	`crates/tools/stub-scan`
Vocabulary in force (lexicon)	`current`

Tier flow. Which tiers this crate's own edges cross.

flowchart LR
  n_tools["tools"] --> n_application["application"]

Dependencies

Runtime, in this workspace.

Crate	Tier	Optional	Only on
`application-core`	application	no	always

Runtime, from outside the workspace.

Crate	Requirement	Features	Optional	Only on
`anyhow`	`^1`	—	no	always
`serde`	`^1`	`derive`	no	always
`serde_json`	`^1`	—	no	always
`sqlx`	`^0.8`	`runtime-tokio`, `postgres`, `chrono`, `uuid`, `json`, `runtime-tokio`, … (9 total)	no	always
`tokio`	`^1`	`full`, `macros`, `rt-multi-thread`	no	always

Development. None.

Build. None.

Depended on by. 1 workspace crate.

Signal flow — what reaches this crate, and what it reaches.

flowchart LR
  n_tools_corpus["tools-corpus"] -->|uses| SELF
  SELF["tools-stub-scan"]
  SELF -->|runtime| n_application_core["application-core"]
  classDef self fill:#1f883d,stroke:#1f883d,color:#fff;
  class SELF self;

Feature flags

No Cargo features are defined: every capability is unconditional, so no consumer can receive a half-wired crate.

Targets

Kind	Name	Source
bin	`tools-stub-scan`	`src/main.rs`
lib	`tools_stub_scan`	`src/lib.rs`

Error model

No public error type was detected: no public item declares a type named *Error, and no public signature returns one.

Operational characteristics

Property	Evidence
async public surface	yes
async runtime	yes
database access	yes
network I/O	none detected
unsafe code	none detected
environment variables	yes

No unsafe block, unsafe fn, unsafe impl or unsafe trait was found by the parser anywhere in this crate's source.

Configuration

Variable	Read in
`CARGO_MANIFEST_DIR`	`src/main.rs`
`CORPUS_SOURCECODE_APP_DB`	`src/main.rs`

1 workspace crate depends on this one: tools-corpus.

Verification

Kind	Count
Unit tests	9
Integration tests	0
Examples	0
Doctests	0

Evidence by module. How often each public module is named by something executable.

Module	Tests	Examples	Consumers
`crate root`	12	0	4
`store`	7	0	4

What the tests establish, by name:

forge_crates_group_at_two_segments — src/lib.rs
issue_title_is_stable_and_body_lists_every_site — src/lib.rs
splice_replaces_existing_block_idempotently — src/lib.rs
structured_markers_match_only_in_comments — src/lib.rs
todo_macro_in_code_is_a_hard_stub — src/lib.rs
todo_word_inside_string_or_comment_is_not_a_hard_stub — src/lib.rs
word_boundaries_hold — src/lib.rs
kind_vocabulary_round_trips_and_refuses_unknowns — src/store.rs
snapshot_replaces_rather_than_accumulates — src/store.rs

Documentation coverage

Measure	Documented	Total
Public items with rustdoc	17	20
Public modules with a `//!` block	1	1

pie showData
    title Public items with rustdoc
    "Documented" : 17
    "No rustdoc detected" : 3

Metrics

Metric	Value
Rust source files	3
Source lines	1011
Code lines	816
Public API items	20
Public modules	1
Tests	9
Examples	0
Cargo features	0
Direct runtime dependencies	6
Workspace reverse dependencies	1

pie showData
    title Public API by kind
    "constant" : 4
    "enum" : 1
    "function" : 13
    "method" : 1
    "struct" : 1

pie showData
    title Rust source composition
    "Code" : 816
    "Blank or comment" : 195

Generation

Rendered by tools-corpus corpus readme from repository evidence alone, renderer schema 2, lexicon current. No model, network service or database was consulted. Regenerate with tools-corpus corpus readme --write; verify with --check.

What it is for

Capabilities

crate root

Finding

Kind

store (other)

How to use it

Module structure

Public surface

Boundary

Where it sits

Dependencies

Feature flags

Targets

Error model

Operational characteristics

Configuration

Related capabilities

Verification

Documentation coverage

Metrics

Generation

`crate root`

`Finding`

`Kind`

`store (other)`