cursus.validation.alignment.analyzer.script_analyzer

Contract-Focused Script Analyzer

Analyzes Python scripts for contract alignment validation. Focuses on main function signature and parameter usage patterns.

Based on analysis of actual scripts: - currency_conversion.py - xgboost_training.py

class ScriptAnalyzer(script_path)

Bases: object

Contract alignment focused script analyzer.

Validates: - Main function signature compliance - Parameter usage patterns (input_paths, output_paths, environ_vars, job_args) - Contract alignment validation

validate_main_function_signature()

Validate main function has correct signature.

Expected signature: def main(input_paths: Dict[str, str], output_paths: Dict[str, str],

environ_vars: Dict[str, str], job_args: argparse.Namespace) -> Any

extract_parameter_usage()

Extract how script uses main function parameters.

Returns:

• input_paths_keys: Keys used in input_paths[“key”] or input_paths.get(“key”)

• output_paths_keys: Keys used in output_paths[“key”] or output_paths.get(“key”)

• environ_vars_keys: Keys used in environ_vars.get(“key”)

• job_args_attrs: Attributes used in job_args.attribute

Return type:

Dictionary with parameter usage patterns

validate_contract_alignment(contract)

Validate script usage aligns with contract declarations.

Parameters:

contract (Dict) – Contract dictionary with expected_input_paths, expected_output_paths, etc.

Returns:

List of validation issues

Return type:

List[Dict]

extract_argparse_flags()

Extract every parser.add_argument(...) declared ANYWHERE in the module.

Walks the WHOLE module (not just main) because the parser lives in a module-level if __name__ == "__main__": block (often inside a try:), and may sit in a helper. Returns one record per add_argument: {flag, canonical, dest, required, choices, has_default, dynamic} where canonical (the normalized flag) is the comparison key and dynamic marks a non-constant flag (built from a variable — absence can’t be proven).

extract_env_reads()

Find env-var keys the script READS, in two tiers (the Cat-5 two-tier rule):

• all: every key referenced anywhere via os.environ.get / os.getenv / os.environ[...] (Load) / environ_vars.get / environ_vars[...] (Load).

• consuming: keys read in a CONSUMING position — an environ_vars.* access inside main()’s body, OR an os.environ.*/os.getenv read that is NOT merely a value harvested into a module-level environ_vars = {...} dict literal. A var that is only harvested into that dict but never consumed in main() is exactly the Cat-5 bug, so it must NOT count as consuming.

Env writes (os.environ['K'] = ... — Store ctx) are excluded from both tiers.

validate_reverse_alignment(contract, sagemaker_step_type=None)

Reverse-direction alignment: does the script PARSE the args / READ the required env the contract+builder declare? Returns issues in the same schema the forward checker emits, so a caller can .extend() them into one issues[]. Additive — the forward methods the B1 validator consumes are untouched.