To be clear, I don’t think you can “overuse” types. The problem with your code is that there were several instances of types with the same/similar names and they weren’t properly documented. In fact, the situation was confusing enough that you made mistakes yourself when writing the specs, so it will definitely be confusing for any other programmers.

What I mean is that types are like code. They should ideally mean one specific thing, should exist in one place, and should be documented clearly. So for a given “shape” of data, define a typespec for it in one single place, and have all specs that work with that data “reuse” the typespec by referring to it: don’t declare it again in the same module.

If you need different typespecs for similar but different data (e.g. item before processing VS item after processing), then absolutely declare 2 different types but make sure their names are clear, and they’re properly documented.

After taking a quick look at your code I would suggest you take a look at Decimal for your calculations. You can find many articles on why you should not use Float.

Your problem is what dialyzer is telling you: you’re not allowed to call initialize_cart_product/2 with (number(), Item) because the spec says it accepts (number(), input_item()).

Indeed, if you look at the definition of input_item/0 in shopping_cart.ex and compare to the item/0 in receipt_csv_parser.ex (which is what you’re passing to initialize the cart product), you’ll see they don’t match (their price and quantity types differ).

Some general tips:

• you should put all of your modules within a top-level namespace unless you have a good reason not to do so (e.g. Item should be SalesTax.Item). Alias them where they’re used if you’re worried about long module names. Otherwise, any project using your code is going to have a conflict if they (e.g.) also define an Item struct. See here. Note that nothing forces you to do it, but it’s a good convention to follow.

• you should probably use String.t instead of binary: they’re the same to analysis tools, but String.t makes it more obvious what you’re working with.

• you’re sprinkling typing information all over your code. This makes it hard to understand and (as you’re finding out) hard to maintain.

For your specific case, I would suggest doing this:

# item.ex
@type t :: %__MODULE__{
    :basic_sales_tax_applicable => boolean(),
    :imported => boolean(),
    :name => binary(),
    :price => number(),
    :quantity => integer()
}

Then, everywhere else (e.g. here) use that value in your specs:

  @spec initialize_cart_product(number, Item.t()) :: Item.t()
  def initialize_cart_product(total_sales_tax_from_one_item, product) do

If you want to differentiate items before/after processing, you can declare additional “sub-types” in item.ex, e.g.:

# item.ex
@type t :: before_processing | after_processing

@type before_processing :: %__MODULE__{
    # type info
}

@type after_processing :: %__MODULE__{
    # type info
}

You’re not specifying the types and specs correctly. See how you should be doing that here.

For example, in lib/receipt_csv_parser.ex the spec for read_line_items/1 should be @spec read_line_items(String.t) :: list(String.t). The main error of the spec you have is String doesn’t mean anything. The string type is given by String.t/0

In the same vein, Item isn’t a type. You need to define it’s type like this (e.g.):

# in item.ex

@type t :: %__MODULE__{}

Then, back in lib/receipt_csv_parser.ex you can fix the spec for imported?/1 by making it @spec imported?(Item.t) :: boolean.

For the issue on line 56, dialzyer is telling you what the problem is: ShoppingCart.initialize_cart_product/2 takes a number/0 as the first argument, but you’re giving it the return value of SalesTaxCalculator.calculate_total_sales_tax/1 which is a float/0 per the specs you defined.

Regarding the “no local return” error, this often means that the body of the function can raise an error (in which case no return value would be provided). To find out what the issue is, try commenting lines (or replacing them with dummy lines that ensure the types work in your code) to find the line causing triggering the dialyzer issue. Then, either fix your code/specs, or add no_return as a possible return value.