Repository navigation
Tags
Tags
Keep FS1182 a warning when verifying signatures (#377) * Keep FS1182 a warning when verifying signatures A signature hides bindings the implementation no longer exposes, and the compiler then reports them as unused (FS1182). A project that promotes that warning to an error, as Fantomas does with WarningsAsErrors, failed the verify step over code that compiled a moment ago, and no signature was written. typeCheckProjectWithSignatures now appends --warnaserror-:1182 to the project's options for that check only. The flag goes last so it wins over whatever the project passed. The pre-run compile check is untouched. Add a test that reproduces the setup and fails without the change. * Leave out empty and private nested modules A nested module with nothing left in its signature was written as `module M = begin end`. It says nothing about the API and the compiler accepts the implementation without it, so it is left out. Errors from its children are still reported. A `private` nested module is left out the same way private let bindings are, even when it has bindings. --include-private-bindings keeps it. Fixes #376 * Update changelog * Add type to string interpolation
Remove XML doc comments the signature took (#374) * Remove XML doc comments the signature took over from the implementation Tooling reads the docs of a declaration from the signature file when there is one, so a second copy in the implementation only drifts apart from it. The docs of every declaration the signature has are now removed from the implementation, after verification, the same way redundant private keywords are. --keep-xml-docs opts out. Only docs the signature actually carries are touched: the ranges come from the XmlDoc nodes of the generated signature tree, which still point into the implementation. Docs on private bindings, on bindings left out as unused, and on declarations the writer drops stay where they are. Also fix the "only used" default for a file that already has a signature file. FCS reports the declaration location of its bindings in the .fsi, so every use from another file was rejected as not declared in the implementation, and all bindings were left out. The implementation location is used instead. Rerunning Telplin on a file with an existing signature is a normal use, to shorten the signature and clean up the implementation. * Changelog
Various fixes and good stuff (#373) * Sanitize DefaultParameterValue with a struct default in FCS signature text FCS prints a DefaultParameterValue whose value is the default of a struct, such as Nullable<TimeSpan>(), as `(default :> obj)`. That is not valid F#, so the pseudo-signature could not be parsed and the member was left out of the signature file. The parameter attributes from the source are used in the final output, so the FCS text only needs to be parseable. Replace the fragment with `null` before parsing. Fixes #348 * Add troubleshooting scripts, Claude commands and a script check stage Debugging a signature issue means looking at three things: the text FCS returns from GetValSignatureText, the Fantomas Oak that text and the source parse to, and what Telplin makes of both. Until now that meant writing a throwaway script each time. scripts/ holds three runnable scripts for this, using the NuGet packages pinned in Directory.Packages.props rather than a local build of FCS or Fantomas: - symbols.fsx: type check the input and print the raw signature text of every definition, optionally the FCS GenerateSignature output too. - oak.fsx: print the Oak of a source or signature file, or of a single member line wrapped the way mkMemberSigFromString does it. - telplin.fsx: run the locally built Telplin.Core and print the signature, the Telplin errors and the diagnostics of compiling both files together. .claude/ gets a command for each script and a telplin-issue skill that walks through reproducing, testing and fixing a GitHub issue with them. The contributing docs mention the scripts. The Build pipeline gains a scripts stage that compiles the scripts with --typecheck-only against a debug build of Telplin.Core. Nothing else in the build looks at them, so without this a rename in src/ would break a script silently until the next time somebody needed it. * Strip the ModuleSuffix module name FCS puts in front of nested types For a type declared in a module with ModuleSuffix, explicit or implicit when a type shares the module's name, FCS renders the type in GetValSignatureText as `Telplin.V` even from inside that module. The compiled name of the module is `TelplinModule`, so its own open path never matches and the display name gets prepended. Inside the module `Telplin` does not resolve, and the signature file failed to compile. Remove that leading segment for every enclosing module with a suffix. Only a leading segment is touched, so `Other.Telplin.V` and `MyTelplin.V` stay as they are. Also add a regression test for a backtick inside a backticked name, which the FCS update fixed on its own. Fixes #71 Fixes #88 * Keep going when one declaration fails, and underline it in the report A declaration Telplin could not convert was already left out of the signature, but an exception in one of them ended the whole run, and the errors were printed as a bare Fantomas range that nothing could jump to. In a large file that made finding the offending declaration a needle in a haystack. Every declaration and member is now converted under a guard: an exception becomes an error for that item and the rest of the file is still produced. The two `todo` failwiths say what they hit. The folds over declarations and members share one processResults that returns what each item became or the error it raised, which also replaced the continuation based walk of recursive nested modules. The CLI reports each left out declaration the way Fantomas reports a parse error: a compiler style `file(line,col): error: message` headline, then the surrounding lines with a line number gutter and carets under the declaration. Progress lines and warnings move to stderr so stdout holds results only, and colour is turned off when either stream is redirected since one theme serves both. Tests cover the partial signature: the rest of the file is kept and still compiles with the implementation. Closes #72 * 0.15.0
Accept a single source file as input (#372) * Accept a single source file as input A .fs file now stands for the project it belongs to, and is the one file processed. The folders above the file are walked upwards; in each one that holds project files, MSBuild is asked for their Compile items, so a file brought in by a glob or an import is found as well. Two projects that both have the file is an error listing them, as is none at all. This makes the common case a one-liner: point Telplin at the file and pass --only-used, without naming the project and --files. * Update changelog * Leave out unused let bindings by default A signature file is most useful when it exposes only what the rest of the project needs, and that is what most runs are after. Bindings no other file of the project uses are now left out without asking for it. --keep-unused keeps them, for a public API where use from outside the project is not seen. --include-private-bindings implies --keep-unused rather than contradicting it, since private bindings are unused by definition. The old --only-used flag is refused with a pointer to the new one.
Verify the project compiles before and after (#371) * Verify the project compiles before and after generating signatures Telplin reads types off a project that compiles, so a project that does not is refused up front with its diagnostics, instead of producing signatures from an unreliable check. Once the signatures are generated, the whole project is type checked again with each one placed in front of its implementation, served from memory. A file checked on its own is not enough: a signature hides what later files could see. When the check fails the diagnostics are printed and nothing is written, exit code 1. `--no-verify` skips the check, `--force` writes despite it. A run reports what it wrote and says that the files are not listed in the project yet, with the `<Compile>` item to add before each implementation file. The generated `AssemblyInfo.fs` and `AssemblyAttributes.fs` are skipped. A full run used to write a signature for both into the intermediate folder. * List new signature files in the project, resolve --files more forgivingly When the input is a project file, each written signature is added as a `<Compile>` item directly before its implementation file. The edit is textual: the inserted line takes the indentation, path separator and line ending the project already uses, and nothing else in the file moves. A signature that is already listed is left alone, so a rerun changes nothing. An implementation that is not a literal item, brought in by a glob, a property or an import, is reported for the user to place. `--no-project` opts out. A `--files` argument no longer has to be relative to the working directory. A path that exists as given wins; otherwise it is matched against the end of the project's source paths, so `Arguments.fs` or `Telplin/Arguments.fs` finds the file from anywhere, for an .rsp input as much as for a project. No match, or more than one, is refused before anything is generated. * Add --only-used, drop redundant private keywords, document the flags `--only-used` leaves a module-level let binding out of the signature when no other file of the project uses it, which makes it private. A signature is more useful the less it exposes, and for a file internal to a project the rest of that project is the whole audience. Only the project is looked at, so a binding used by another project, by tests, through reflection or by consumers of a library is not seen; the flag is opt-in and its help text says so. Types, members and bindings with an attribute (an entry point, a test, a literal) are always kept. The uses come from the project check the run already does. Combining it with `--include-private-bindings` is refused. With a signature file in place, `private` on a let binding the signature leaves out says nothing the signature does not, so after a verified write the keyword is removed from the implementation. `--keep-private` leaves it. Members are not touched. The console application gains signature files of its own, and the usage page and README describe what a run does and list the flags, with `--only-used` on a single file as the leading example. * Accept a folder as input, add the 0.13.0 changelog entry A folder given as the input stands for the one project file in it. With none, or with several, there is nothing to pick, so the run says so and lists what it found rather than guess. The help page and the usage docs mention the folder form. The changelog gets a 0.13.0 entry covering --only-used, the verification before and after a run, the project file update, the removal of redundant private keywords, the more forgiving --files and the folder input. * Create a GitHub release for each new changelog entry After the NuGet push, the Build pipeline creates the GitHub release for the newest entry of CHANGELOG.md: tag vX.Y.Z, the entry's sections as the notes, the nupkg attached, marked prerelease when the version says so. An entry that already has a release is left alone, so a rerun or a push that does not touch the changelog changes nothing. The workflow gets `contents: write` and a GH_TOKEN for that step.