jackal-notes.txt

* refine this file based on conventions adopted for
  notes.txt files used for niche and jell

* possibly could split out search-paths so jackal, jargon, and jog can
  vendor search.janet from some common place?  might be that
  walk-dir.janet and search.janet should be merged?

* unexpected...why does path-join show up as result 8 below?

~/src/git-some-janets/repos$ jakl who-calls declare-project
# searching space: (".") ...

# 1 # emacs +846 ./github.com/janet-lang/spork/spork/declare-cc.janet
quickbin

# 2 # emacs +897 ./github.com/pyrmont/markable/bundle/spork/declare-cc.janet
quickbin

# 3 # emacs +15 ./github.com/pyrmont/markable/bundle/init.janet
build

# 4 # emacs +897 ./github.com/pyrmont/predoc/bundle/spork/declare-cc.janet
quickbin

# 5 # emacs +898 ./github.com/pyrmont/jeep/deps/spork/spork/declare-cc.janet
quickbin

# 6 # emacs +901 ./github.com/pyrmont/blueshift/bundle/spork/declare-cc.janet
quickbin

# 7 # emacs +901 ./github.com/pyrmont/sled/bundle/spork/declare-cc.janet
quickbin

# 8 # emacs +1 ./github.com/sogaiu/janet-tree-sitter/project.janet
path-join

# search space: (".")
# common prefix: "./"
# files searched: 5609
# files analyzed: 603
# number of results: 8
# processing time: 0.82 seconds

  seems like a bug.  result 8's file does not seem to have any
  callables that call declare-project.

* limits and bugs

  * taking a long time on large files is not easily
    distinguishable from an infinite loop.

    in ~/src/jell:

    $ jakl who-calls j/path 
    # searching space: (".") ...

    good opportunity to add verbose mode?

    at least showing which file is being processed (in
    search-paths) in a verbose mode might be helpful.

    possibly something like maybe-dump from jell
    could be useful to report on some of the
    currently executing functions (e.g. collect-paths
    and search-paths)

  * no option for result paths being absolute

  * reporting occurs after all searching is complete.  might
    be nicer if results are printed more incrementally from
    ux perspective.

  * output formatting is not modular
    * customizability might be nice to avoid having to spend
      too much effort "polishing"?

  * no easy way to setup completion

  * command and options are not echoed in output

  * forms within comment forms are not skipped

  * no color output
    * just pipe to bat or something similar?
    * jref might have some work related to this

  * `who-calls` displays the definition name of something, which
    may be a substring of the actual name used in a call
    (which could be prefixed with <name>/, e.g.):

      $ jakl who-calls search-paths lib

    yields:

      # searching space: @["lib"] ...

      # emacs +7 lib/commands.janet
      search-and-dump

      # emacs +24 lib/commands.janet
      search-and-report

      # search space: @["lib"]
      # common prefix: "lib/"
      # files searched: 8
      # files analyzed: 2
      # number of results: 2

    which mentions `search-and-report` instead of `s/search-and-report`

    `who-calls` uses `find-callers-of` which explicitly saves the caller
    name, but this is obtained from the definition so it is likely not
    prefixed.

* output
  * revisit human-readable output
    * take notes about problems
      * indentation sub par in parts
      * kind of cluttered?
        * sparse form of output?  e.g. don't have statistics
  * explore output formats (e.g. tsv, etc.)

* testing
  * cli invocation testing
    * this is complicated by not having an output format
      decided on?
    * revisit human-readable output format
    * is it really important to test the binscript?
      * possibly to make sure it runs
      * then being able to execute the script "in tree" might be
        a good idea afterall?

* investigate why (import @prefix...) approach for distinguishing
  ./bin/jakl execution from jakl execution was failing
  * somehow (import @prefix/lib/cli) was not working from
    ./bin/jakl being executed from repository root

* optional behavior to process .jeat.conf to determine which
  files to process (instead of "." by default if no paths
  specified?)

* shell completion
  * "adds extra space" issue: https://unix.stackexchange.com/a/504917
    * revisit other projects that didn't use -o nospace?
  * better than nothing initial approach
  * how to also complete file paths after command name completion

_jakl_ids() {
    COMPREPLY=( $(compgen -f -d -W "all-calls who-calls calls-to" -- ${COMP_WORDS[COMP_CWORD]}) );
}
complete -o nospace -F _jakl_ids jakl

  * hack for allowing execution from repository root may not work
    well with shell completion

* credits
  * pyrmont - string/find suggestion

* other ideas

  * code to rewrite `(use ...)` as `(import ...)` and make related
    adjustments throughout source (e.g. symbols that were made
    available via `use` should be updated to match the appropriate 
    alias from `import`.

* hidden features

  * .jakl.conf support
    * each line should be one of:
      * one file / dir path
      * a comment beginning with #
      * blank (just whitespace)
  * searching current directory if no path supplied
  * shortcut names for subcommands
  * actually tries to search janet-shebanged files too
  * optional struct at cli for specifying options
    * :dump true gives jdn(-ish) output
    * :stop-watch false prevents processing time output
    * :no-prefix false disables full path display for editor invocation
    * :exact-match true enables exact match searching
    * :limit-lines n for n > 0 limits lines per result to n
      * note this can break syntax highlighting

* pre-commit steps

  1. run jell and examine results

     * if problem detected, investigate, take action, and go to step 1

  2. run tests and examine results

     * if problem detected, investigate, take action, and go to step 1

  3. copy jakl.janet to jakl

  4. ensure README is up-to-date

  5. assemble and review staging for commit

     * if it looks like changes are needed, make them and go to step 1

     * if not, commit and push