feature-to-code-map.md

title	Feature To Code Map
audience	developers, contributors
prerequisites	source map, testing strategy
related	source-map.md, ../user/language-support/feature-matrix.md
status	maintained
publication	draft

Feature To Code Map

Use this page when starting from a user-visible feature. The table points to the public docs, implementation files, focused tests, and evidence required before documentation may call the behavior supported.

Feature Map

Feature or behavior	Public docs	Main implementation files	Focused tests	Support evidence
Fortran parse output	docs/developer/fortran-parser-reference.md	prik/parsers/fortran/parser.py, models.py, lexer.py, type_resolver.py	tests/fortran/source_parsing/parsing/, tests/fortran/source_parsing/parsing/test_fortran_fixture_suite.py	Parser facts and diagnostics match fixtures
Semantic .pyi generation	docs/user/reference/semantic-pyi-format.md	prik/wrapper_codegen/printers/pyi_printer.py	tests/fortran/semantic_pyi_format/pipeline/, tests/fortran/semantic_pyi_format/pipeline/test_modern_example.py	Printed .pyi round-trips or matches fixtures
Semantic .pyi conversion and editing	docs/user/reference/pyi-contracts/index.md, docs/user/reference/semantic-pyi-format.md, docs/user/examples/recipes/semantic-pyi-contracts.md	prik/parsers/pyi/parser.py, prik/pipeline/pyi.py, prik/semantics/pyi2ir.py, models.py	tests/fortran/semantic_pyi_format/	Edited contracts parse to Python AST, then become semantic IR with preserved native facts
Semantic and wrapper-planning errors	docs/user/guide/error-handling.md, docs/user/reference/diagnostic-codes.md	prik/semantics/fortran2ir.py, prik/semantics/policy_completion.py, prik/wrapper_codegen/planner.py	tests/fortran/infrastructure/policy/, feature-local policy/, and feature-local wrapper_codegen/ tests	Each owning stage rejects unsupported or incomplete contracts
Fortran wrapper orchestration	docs/user/reference/fortran-wrapper.md, docs/user/guide/building-shared-library.md	prik/pipeline/build.py	tests/fortran/building_shared_library/end_to_end/test_source_build_modes.py, multi-source wrapper tests	Builds report artifacts and compile/link as documented
Completed semantic policy to wrapper artifacts	docs/user/reference/fortran-wrapper.md	prik/semantics/policy_completion.py, prik/wrapper_codegen/plan.py, planner.py, generator.py	tests/fortran/infrastructure/policy/, tests/fortran/infrastructure/wrapper_codegen/, and feature-local policy/codegen tests	Runtime policy is explicit, the typed plan is complete, and generated artifacts compile and run
Native compilation and binding support	docs/user/reference/fortran-wrapper.md, docs/user/guide/building-shared-library.md, docs/developer/build-system.md, docs/developer/quality-assurance.md	prik/compiling/, prik/binding_support/	tests/fortran/building_shared_library/end_to_end/test_runtime_compatibility.py, build-mode tests	Generated sources compile, link, import, and clean up correctly
Source documentation structure	docs/developer/source-map.md	docs/, package README files, tests/shared/docs/test_structure.py	documentation structure and example tests	Pages have metadata, audience separation, and source coverage checks

First-File Rule

When the user-visible behavior changes, update the public docs in the same row before or alongside the implementation. The documentation structure test keeps this routing page tied to the source hotspots and package README files.

Workflow Feature Pointers

User workflow	Start in code	Do not mark supported until
Wrapping functions and subroutines	prik/semantics/fortran2ir.py, policy completion, prik/wrapper_codegen/planner.py, bridge and binding generators	Runtime tests compile, import, call, and verify return and failure behavior
Wrapping modules and module variables	parser module facts, semantic module conversion, naming policy, wrapper generators	Python-visible names, accessors, and unsupported module constructs are tested
Arrays and allocatables	semantic array contracts, ownership policy, typed wrapper plans, bridge/binding array handlers	dtype, shape, rank, contiguity, mutation, returned arrays, and failure paths are tested; ordinary NumPy array actuals validate and extract their buffer directly in the C binding, descriptor handles use the planned runtime-handle path, and strided contracts carry a dense-actual role for zero-copy fast-path selection
Pointer arguments	semantic metadata, ownership policy, bridge/binding pointer handlers	Owner, lifetime, association, and blocked cases are explicit and tested
Optional arguments	parser optional attributes, semantic arguments, binding argument parsing	Present/absent calls and unsupported combinations are tested
Generic interfaces	parser interface facts, semantic overload sets, FunctionOverloadSet, binding dispatch	Overload selection and ambiguity failures are tested at runtime
Enumerations	parser enum facts, semantic constants/classes, codegen projection	Python-visible values and unsupported enum forms are tested
Packaging and distribution	prik/pipeline/build.py, prik/compiling/, future packaging integration	Build artifacts, native dependencies, and platform constraints are documented and tested

Evidence Rule

A feature can appear in user workflow docs only after the implementation, focused tests, and runtime evidence match the public claim. Parser or semantic support alone is not enough for runtime wrapper support.