Module codegen 

Scaffolding primitives — how a command writes code into the user’s project.

umbral startcommand needs these. So does any plugin that wants to generate code: umbral-rest ships startpermission / startauthentication / startpagination / startthrottle, and a third-party plugin can ship its own generator with nothing more than the facade. That’s the whole point of putting this in core rather than in umbral-cli: a plugin can’t depend on the CLI (dependencies point inward), so if the file surgery lived there, every plugin generator would hand-roll its own — and hand-rolled mod insertion is how a generator eats somebody’s main.rs.

What’s here is deliberately small and boring:

• Target / resolve_target — “root or which plugin?”, the question every generator asks, answered against what’s actually on disk.
• write_new_file — write, never overwrite.
• declare_module / insert_before_marker — the two edits a generator makes to a file it doesn’t own.

Every function that edits an existing file returns Option/Result and declines when the file isn’t the shape it expected. A generator that guesses at a file it doesn’t recognise is a generator that corrupts it; the caller reports the lines to add by hand instead.

Modules

prompt

Terminal prompts for a generator that asks before it writes.

Structs

ResolvedTarget

A resolved Target: the crate to write into, and the file that owns its module tree.

Scaffolded

What a generator wrote, for the report it prints.

Enums

CodegenError

Errors a generator can hit before it writes anything.

Target

Where generated code lands: the project’s own crate, or one of its plugins.

Functions

declare_module

Add a module declaration (mod foo; / pub mod foo;) to a file’s module list, placed before the first existing declaration so the list stays readable at the top of the file.

discover_plugins

The plugins available in this project: every plugins/<name>/ that holds a Cargo.toml.

ensure_dependency

Ensure <name> = <spec> is listed under [dependencies] in a Cargo.toml.

insert_before_marker

Insert line immediately before the line that equals marker (trimmed).

insert_before_marker_once

insert_before_marker, but a no-op when line is already in the file.

insert_line_after

Insert line after line index idx, preserving the file’s line style.

insert_line_before

Insert line before line index idx, preserving the file’s line endings and its trailing-newline habit.

pascal_case_from_ident

Convert a kebab/snake-case identifier or user-provided name into PascalCase for use as a Rust type name or plugin struct name.

resolve_target

Resolve a Target against the project on disk.

to_snake_case

Convert a PascalCase or camelCase Rust identifier into snake_case.

validate_ident

Validate a name as a Rust identifier stem: ASCII alphanumeric, _, -, not starting with a digit, not empty, not a Rust keyword.

write_new_file

Write a file that must not already exist, recording it in files (relative to crate_root) for the report.