Module Superbol_free_lib.Project_commands

Helpers for commands that analyze files within their projects, according to their configuration, reusing and filling the caches of these projects.

module CACHE = Superbol_cache.Cache
module CACHING = Superbol_cache.Caching
module RECORDER = Superbol_cache.Recorder
module WITNESS = Superbol_cache.Witness
module ANALYSIS = Superbol_project.Analysis
type setup = {
  1. project_root : string option;
    (*

    Root of the project of every file (detected for each file otherwise)

    *)
  2. layout : Superbol_project.layout;
  3. storage_location : Superbol_project.TYPES.cache_storage_location;
  4. client_settings : (string * Yojson.Safe.t) list option;
    (*

    Settings of an LSP client, for projects without configuration file

    *)
  5. encoding : Cobol_common.Text_encoding.t option;
    (*

    Encoding to decode files with (as an LSP client does), overriding the source_encoding of projects

    *)
}

How projects are set up, and where their caches live. Functions below that take an optional setup default to default_setup.

val default_setup : setup
val lsp_like_setup : ?storage_directory:string -> ?client_settings:(string * Yojson.Safe.t) list -> ?encoding:Cobol_common.Text_encoding.t -> unit -> setup

lsp_like_setup ?storage_directory ?client_settings ?encoding () sets projects up as an LSP server started with --storage-directory storage_directory does, whose client sends client_settings and decodes files with encoding.

val cache_for : ?setup:setup -> string -> (string * Superbol_cache.Cache.t) option
val configured_projects : (string, Superbol_project.project) Stdlib.Hashtbl.t
val settings_reporter : Cobol_lsp.Project.settings_reporter
type located_file = {
  1. filename : string;
  2. project : Superbol_project.t;
  3. contents : string;
  4. cached : (CACHE.t * ANALYSIS.keys) option;
}
type 'a analyzed_file = {
  1. filename : string;
  2. project : Superbol_project.t;
  3. contents : string;
  4. analysis : 'a;
  5. hit : bool;
}

'a is either ANALYSIS.t or ANALYSIS.for_lsp.

val cached_configs : (string, Superbol_project.t * ANALYSIS.overrides * (Superbol_cache.Cache.t * ANALYSIS.config_inputs) option) Stdlib.Hashtbl.t
val cached_config : setup:setup -> overrides:ANALYSIS.overrides -> Superbol_project.t -> (Superbol_cache.Cache.t * ANALYSIS.config_inputs) option
val locate : ?setup:setup -> Common_args.t -> string -> located_file
val analyze_located_for_lsp : Common_args.t -> located_file -> Superbol_project__.Project_analysis.for_lsp analyzed_file
val analyze_file : ?setup:setup -> Common_args.t -> string -> ANALYSIS.t analyzed_file

analyze_file common filename analyzes filename according to the configuration of its project and the overrides in common, reusing or else filling the project's cache.

val analyze_file_for_lsp : ?setup:setup -> Common_args.t -> string -> ANALYSIS.for_lsp analyzed_file

analyze_file_for_lsp common filename is like analyze_file, except that it provides an analysis for the LSP. Use this to get all artifacts the LSP would need, or to fill the cache for the LSP.

val derived_entry : label:string -> inputs:Superbol_cache.Types.digest list -> located_file -> (CACHE.t * Superbol_cache.Types.key * Superbol_cache.Types.key * ANALYSIS.keys) option

derived_entry ~label ~inputs located is the cache, key and slot of the derived entry, for located, along with the keys of the analysis it may derive from.

analyze_located_n_witness common ~cache ~keys located is the analysis of located, along with the key of the cache entry it is held in: the analysis for the LSP if cache holds one, or else the (normal) analysis, computed and stored on a miss.

val derive_located : Common_args.t -> label:string -> inputs:Superbol_cache.Types.digest list -> derive:(ANALYSIS.t analyzed_file -> 'a) -> located_file -> 'a * bool * ANALYSIS.t analyzed_file Stdlib.Lazy.t
val derive_from_file : ?setup:setup -> Common_args.t -> label:string -> inputs:Superbol_cache.Types.digest list -> derive:(ANALYSIS.t analyzed_file -> 'a) -> string -> 'a * bool

derive_from_file common ~label ~inputs ~derive filename is derive applied to the result of analyze_file on filename. The result is cached in the project's cache, along with the analysis it is derived from (which may be one for the LSP if the cache holds it): a hit on the derived value requires the analysis itself to be a hit, and does not entail retrieving the latter.

label identifies the derivation, and inputs should hold digests of everything derive depends upon besides the analysis result. The Boolean indicates a hit.

Note that derive must return a value that holds no closure, and be fully determined by the producer (as identified by the cache), the analysis, and inputs.

val derive_n_analyze_file : ?setup:setup -> Common_args.t -> label:string -> inputs:Superbol_cache.Types.digest list -> derive:(ANALYSIS.t analyzed_file -> 'a) -> string -> 'a * bool * ANALYSIS.t analyzed_file

derive_n_analyze_file common ~label ~inputs ~derive filename is like derive_from_file, except that it also returns the analysis of filename, which is retrieved from the project's cache in case of a hit on the derived value. Use this to only cache, as derived value, what can not be obtained from the analysis directly.

val lookup_located : Common_args.t -> label:string -> inputs:Superbol_cache.Types.digest list -> located_file -> ('a * ANALYSIS.t analyzed_file Stdlib.Lazy.t) option
val lookup_derived : ?setup:setup -> Common_args.t -> label:string -> inputs:Superbol_cache.Types.digest list -> string -> 'a option

lookup_derived common ~label ~inputs filename retrieves a value previously recorded by derive_from_file with the same label and inputs, without analyzing filename; None on a miss.

val lookup_derived_n_analysis : ?setup:setup -> Common_args.t -> label:string -> inputs:Superbol_cache.Types.digest list -> string -> ('a * ANALYSIS.t analyzed_file) option

lookup_derived_n_analysis common ~label ~inputs filename is like lookup_derived, except that it also returns the analysis of filename in case of a hit, which is retrieved from the project's cache (it is computed and stored anew if the cache no longer holds it).

val report : Common_args.t -> ?error_status:bool -> ?show_diagnostics:bool -> ppf:Stdlib.Format.formatter -> ANALYSIS.t analyzed_file -> unit

report common ~error_status ~show_diagnostics ~ppf analysis reports analysis diagnostics on ppf, unless show_diagnostics is false. Errors among them, shown or not, make the program exit with a non-zero status, unless error_status is false. Both default to true.

val analyze_n_report : ?setup:setup -> ?error_status:bool -> ?show_diagnostics:bool -> Common_args.t -> for_lsp:bool -> ppf:Stdlib.Format.formatter -> string list -> unit

analyze_n_report ?setup ?error_status ?show_diagnostics common ~for_lsp ~ppf files analyzes files in turn, and reports diagnostics on ppf. Files are analyzed with analyze_file_for_lsp if for_lsp holds (so the cache is filled for the LSP), or else with analyze_file. See report for error_status and show_diagnostics; files that cannot be analyzed are reported on ppf regardless.

val fold_analysis_results : ?setup:setup -> Common_args.t -> f:(ANALYSIS.t analyzed_file -> 'a -> 'a) -> ppf:Stdlib.Format.formatter -> string list -> 'a -> 'a

fold_analysis_results common ~f ~ppf files acc analyzes files with analyze_file, in turn, reports analysis diagnostics on ppf, and then passes the analysis result and an accumulator to f.

val fold_typeck_outputs : ?setup:setup -> f:(ANALYSIS.t analyzed_file -> Cobol_typeck.Outputs.t -> 'a -> 'a) -> Common_args.t -> string list -> ppf:Stdlib.Format.formatter -> 'a -> 'a

fold_typeck_outputs common ~f ~ppf files acc acts like fold_analysis_results, except f is given the type-checking result as second argument. Therefore f is only called if the type-checking succeeds.