Add comprehensive help text for pyAnalyze and pyAnalyzeLaurel commands

[tautschnig]

Description of changes:

• Rename argument from 'file' to 'ion_file' for clarity
• Add detailed description explaining the command's purpose
• Document both arguments with clear usage information
• Specify verbose mode options (1 for verbose, 0 for concise)

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[Copilot]

Pull request overview

Improves the CLI help/usage text for the pyAnalyze subcommand to better explain expected inputs and verbosity behavior, and adjusts --help output formatting to accommodate longer help strings.

Changes:

• Renames pyAnalyze positional argument label from file to ion_file.
• Expands pyAnalyze help text with detailed argument descriptions and verbose-mode behavior.
• Changes strata --help output to print command usage and help on separate lines.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[tautschnig]

Expanding the proposed changes to a discussion: the new output, for me, looks like this:

$ lake exe strata --help
[...warnings...]
Usage: strata <command> [flags]...

  javaGen <dialect-file> <package> <output-dir>
      Generate Java classes from a DDM dialect file.
  check <file>
      Check a dialect or program file.
  toIon <input> <output>
      Read a Strata text file and translate into Ion.
  print <file>
      Write a Strata text or Ion file to standard output.
  diff <file1> <file2>
      Check if two program files are syntactically equal.
  pyAnalyze <ion_file> <verbose>
      Analyze and verify assertions in a Strata Python Ion file. <ion_file>: path to a .python.st.ion file generated from Python source. <verbose>: set to '1' for verbose output (displays parsed program, Core translation, and inlined program), or '0' for concise verification results only.
  pyTranslate <file>
      Translate a Strata Python Ion file to Strata Core. Write results to stdout.
  pySpecs <python_path> <strata_path>
      Experimental command to translate a Python specification source file.
  laurelAnalyze
      Analyze a Laurel Ion program from stdin. Write diagnostics to stdout.

Flags:
  --include path: Adds a path to Strata for searching for dialects.

Questions:

1. The warnings are actually quite distracting - do we have an issue tracking addressing them?
2. It seems we have both commands for Strata-as-developer-framework (like javaGen) and Strata-as-program-analysis here. Should we really combine them in a single CLI?
3. Some of the subcommands could do with a more verbose help (check-is-check, print sound like it is cat)

[aqjune-aws]

reach to cover

---

this message was supposed to be a commit message, I fumbled :/ But I cannot erase this message for some reason :(

[joehendrix]

The warnings are actually quite distracting - do we have an issue tracking addressing them?

Agreed. Not that I know of, but I think you can check the issues as well as I can.

It seems we have both commands for Strata-as-developer-framework (like javaGen) and Strata-as-program-analysis here. Should we really combine them in a single CLI?

That's probably a good idea to rethink the UI. This started as some utilities for the DDM and has grown.

Some of the subcommands could do with a more verbose help (check-is-check, print sound like it is cat)

Is that a request to rename print to cat? That sounds fine to me.

I'll note I find it a bit distracting to have discussions of unrelated issues in PRs. Discoverability of this seems low.

[tautschnig]

The warnings are actually quite distracting - do we have an issue tracking addressing them?

Agreed. Not that I know of, but I think you can check the issues as well as I can.

Fair, I'll work on this.

It seems we have both commands for Strata-as-developer-framework (like javaGen) and Strata-as-program-analysis here. Should we really combine them in a single CLI?

That's probably a good idea to rethink the UI. This started as some utilities for the DDM and has grown.

Created #447 to track this.

Some of the subcommands could do with a more verbose help (check-is-check, print sound like it is cat)

Is that a request to rename print to cat? That sounds fine to me.

No, it's me asking for help in understanding what those subcommands are actually doing. I'll create another issue.