Reshape the public API before the first release

[vaceslav]

From the pre-release review. Breaking changes are cheap now (0.x, nothing published) and expensive after; decide each before dotnet pack goes to nuget.org.

Blockers

• One exception model with a library base type. Today the same bad plan is ArgumentException from TabularExtractor.Start and TabularStructureException from TabularImporter.Import(Stream…); corrupt files and exceeded ceilings are BCL InvalidDataException; malformed XML leaks XmlException. Proposal: TabularException → TabularFormatException (unreadable/unsupported/corrupt, with a code), TabularLimitException (a bound was hit — which one), TabularStructureException (whole-run fault, with a code), MappingPlanException (carries the MappingFaults). Keep ArgumentException for programmer errors only.
• Fewer namespaces. Seven today (Abstractions, Csv, Xlsx, Analysis, Mapping, Extraction, Import); the documented import needs five usings and ~15 types. Proposal: the workflow in TriasDev.Tabular, format-specific cursors/options in .Csv / .Xlsx.

High

• Internalise implementation types: ColumnProfiler, DistinctBudget, HypothesisBuilder, CsvDialectDetector (add InternalsVisibleTo for tests where needed).
• Public error-code constants (ErrorCodes.ValueRequired = "value.required", …) so callers stop copying strings; keep ErrorCodeCatalogTests checking them against the guide.
• A plan without a UI: e.g. MappingPlan.ByHeader(schema, profile, …) matching headers to field names (case/space/underscore-insensitive), filling SourceHeader from the profile. Needed for a 15-line happy path.
• Unsupported formats: TabularFormat has no way to say "not a format we read"; TabularFile.Detect/Open should recognise OLE2 (.xls), xlsb, ods (for now), and non-text binaries and throw the format exception.
• Stream ownership / leaveOpen is inconsistent: Import(Stream…) always closes, ExtractionSession is IDisposable but owns nothing, TabularFile.Open cannot pass cursor options. One rule for every entry point.
• Cancellation token placement: captured at construction in some layers, per call in others (cursor ReadRow, analyzer). Pick one convention.
• ITabularCursor contract: versioning story for a public interface (default members), and put the csv dialect somewhere other than a CsvCursor cast.

Medium

• Culture spelled three ways ("", "invariant", null) across profile, hypotheses and plan — a top hypothesis's culture cannot be copied into a plan as is.
• Entry points differ per layer (new TabularAnalyzer(opts).Analyze vs static TabularExtractor.Start vs static TabularImporter.Import); align verbs and shapes.
• ImportRun<T> is an IEnumerable that can be enumerated once; make that explicit (or not an IEnumerable) and even out InChunks/All naming.
• PrecheckFinding.Detail is English prose; MappingFault, RowError, PrecheckFinding are three shapes for "a problem" — align fields (code, field, column, row, rows affected, values).
• Generic names that collide in consumer code: TextField, DateField, Pattern, Rule.
• Options records validate nothing (negative bounds, empty cultures) and cannot be reached from TabularFile.Open.
• CsvDialect override is all-or-nothing (must restate encoding + delimiter + provenance to change one).
• Cheap single-sheet analysis, sheet addressing by name, sheet visibility (docs/IDEAS.md).

Low

• Row counters are int in six places and long in one — pick long or document the int ceiling.
• FileProfile.Diagnostics / ImportRun.Summary expose live mutable objects.
• Records with collection/delegate members get reference equality (TargetField, ColumnBinding, Pattern, AllowedValues) — seal equality semantics or use classes.
• Fluent naming (Matching/AtLeast) vs constraint names (Pattern/MinValue); range rules silently no-op on non-numeric fields.
• Pattern matches anywhere in the value (unanchored) — document or anchor.
• After v1 (additive): async/IAsyncEnumerable import for blob streams, analyse-by-path, raw preview grid, IDataReader interop.

Tooling to lock the result in: Microsoft.CodeAnalysis.PublicApiAnalyzers (PublicAPI.Shipped/Unshipped.txt) and package validation — see #3.

[vaceslav]

Stage 2 done. What changed, and what was decided for the rest.

Done

• Exceptions: TabularException base; TabularFormatException (format.unsupported / format.corrupt / format.truncated), TabularLimitException (limit.exceeded, names the option and its value), TabularStructureException (structure.*), MappingPlanException (mapping.invalid-plan, carries the faults). ArgumentException only for programmer errors.
• Namespaces: the workflow is in TriasDev.Tabular; only .Csv and .Xlsx stay separate.
• ColumnProfiler, DistinctBudget, HypothesisBuilder are internal; CsvDialectDetector.Detect(Stream, CsvCursorOptions?).
• ErrorCodes constants, checked against the guide's catalog.
• MappingPlan.ByHeader(sheet, schema, culture) (case, spaces, _ - . ignored) and an overload taking your own match rule.
• .xls / encrypted workbooks, .xlsb, OpenDocument and binary files are refused as format.unsupported.
• Streams: one rule for every entry point. A stream you hand over is closed on every path, failures included, unless you set leaveOpen / TabularOpenOptions.LeaveOpen / ImportOptions.Open.LeaveOpen. TabularFile.Open takes TabularOpenOptions (csv and xlsx options). ExtractionSession is no longer IDisposable.
• Cancellation: every reading operation takes a token as its last parameter (ExtractionSession.ReadRow, ImportRun.Rows, InChunks, All, and the CsvCursor constructor). The token passed to Start / Import still applies to the whole run, so a plain foreach can still be cancelled.
• ITabularCursor.Dialect is a default member, so a wrapping cursor keeps the dialect. New interface members will be added the same way, as default members.
• The invariant culture is always written as "", so the culture of the top hypothesis can go straight into a plan.
• All options are checked where they are handed over (ArgumentOutOfRangeException naming the option).
• Also:
  • ImportOutcome.HasErrors has [MemberNotNullWhen(false, nameof(Value))];
  • PrecheckSeverity is declared in rising order (Undetermined < Warning < Blocking), and findings are sorted most severe first;
  • Pattern is anchored at both ends;
  • a range on a field that is not a number is refused as mapping.constraint-type-mismatch;
  • src and tests build with warnings treated as errors.

Kept as is (decided)

• Row counters stay int. The ceiling is documented: xlsx stops at 1,048,576 rows, and a csv with 2^31 rows would be about 100 GB.
• Entry points: TabularAnalyzer stays an instance, because it checks its options and resolves cultures once and is reused across files. The extractor and the importer stay static because they hold no state.
• ImportRun<T> stays IEnumerable, because foreach is the main way to read it. Reading it a second time throws; Rows(ct) exists for callers who need to pass a token.
• Fluent names (Matching, AtLeast) read as sentences; the constraint records name the rule. The two naming schemes stay.
• TextField / DateField etc. stay; consumers resolve collisions with a using alias.
• Records with collection members keep reference equality. It is documented, not changed.
• FileProfile.Diagnostics / ImportRun.Summary stay live objects with internal setters. They only change if the same cursor or run is read again.

After v0.1 (additive, non-breaking)

• Structured payload on PrecheckFinding (examples, failing and total distinct counts); Detail stays as a debugging aid.
• Overriding only part of a CSV dialect (a delimiter or encoding hint without restating the rest).
• Cheap analysis of a single sheet, addressing a sheet by name, sheet visibility.
• Date ranges.
• Async import, analysis by path, a raw preview grid, IDataReader interop.

[vaceslav]

Add to this list: ITabularCursor.MoveToSheet takes no CancellationToken. For ods it reads forward through the content part, and for a workbook inside an archive it copies the workbook into memory, so a move can take seconds and cannot be stopped. KNOWN-ISSUES describes it. The fix is a token on the interface.

[vaceslav]

Done in #35: the breaking half, released as 0.3.0 once #36 is merged.

It covers:

• static entry points;
• one problem shape, ITabularProblem;
• unique field and schema names;
• precheck data instead of English Detail sentences;
• value equality for data and classes for the schema;
• a run that reads once through ReadRows, ReadChunks or ReadAll, with snapshot summaries;
• a MoveToSheet that can be cancelled.

The constraints keep their names: they are nested types, so there was no collision.

Still open here, and all additive, so they can follow 1.0 without a break:

• addressing a sheet by name;
• sheet visibility;
• a partial CsvDialect override;
• cheap single-sheet analysis;
• async import and IDataReader.