pskfyi / handy Goto Github PK

View Code? Open in Web Editor NEW

0.0 0.0 0.0 224 KB

Utility functions, classes, and types in uncompiled TS, for Deno.

Home Page: https://deno.land/x/handy

License: BSD Zero Clause License

TypeScript 100.00%

deno

handy's Introduction

Patrick Keenan

Who

Father. Nerd. Tech lead. Full stack web developer. Aspiring game maker.

What

Present Obsessions: Deno ⟡ TypeScript

Past: Vue ⟡ Storybook ⟡ Tailwind ⟡ JSON Schema ⟡ Python ⟡ Django ⟡ SQL

Forever: Information Science ⟡ DX & XD ⟡ Philosophy ⟡ Language ⟡ Folklore

Where

Lifelong Northern Californian. Check out this map.

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "coordinates": [
          [
            [-120.98024892262558,39.12926538555507],
            [-121.62398108275471,38.540836803942426],
            [-121.4502048201827,38.36851724860142],
            [-121.30521989105449,38.37093578707177],
            [-121.19519678245007,38.61848711642429],
            [-120.93196173382023,38.64097880824562],
            [-120.75300304080042,38.7100590776478],
            [-120.9144401604679,39.12926538555507],
            [-120.98024892262558,39.12926538555507]
          ]
        ],
        "type": "Polygon"
      },
      "id": 0
    },
    {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "coordinates": [
          [
            [-122.33154165872072,38.16473919891976],
            [-122.44358745791169,37.963952378101425],
            [-122.38954837810272,37.84280319407043],
            [-122.52381538698882,37.80158141057761],
            [-122.50883743989286,37.63379093668679],
            [-122.03874975897133,37.24687517000284],
            [-121.82221640840496,37.19285628042681],
            [-121.73604304664005,37.26039781397411],
            [-121.86247880388902,37.45019536920209],
            [-122.0804518406326,37.460248480252716],
            [-122.32983980829647,37.73336365786372],
            [-122.19845946789789,37.856001475012434],
            [-122.27400897375998,37.942120269087],
            [-122.0524160974957,38.08498799279033],
            [-122.33154165872072,38.16473919891976]
          ]
        ],
        "type": "Polygon"
      }
    }
  ]
}

When

Born in '89, coding since '09.

Why

Memento Mori.

handy's People

Contributors

Watchers

handy's Issues

Version branches should be protected

main is already protected, preventing maintainers from accidental pushes.

Now that 0.3.0 is being handled as a feature branch, we want the same protections for it. We also want the same rules for other semver-like branch names. GitHub's branch protection rules supports a name pattern for this, powered by Ruby's fnmatch.

Consider handy VS Code snippets

https://code.visualstudio.com/docs/editor/userdefinedsnippets

Add a failing test if TODOs left in

Perhaps ignore ".md" files?

Add way to evaluate `@example`s from JSDoc comments

Similar to md/script/evalCodeBlocks. We can use this to assert that our examples are valid code.

`location` is the name of a global; consider renaming `location()` helper

Oops! https://developer.mozilla.org/en-US/docs/Web/API/Window/location

Maybe textLocation() to match the typedef.

Update `cli/cmd` to not throw when using `fullResult` option

`DirectedGraph.Edge` should support arbitrary metadata

If we define Edge as an object instead of an array like {from: "a", to: "b", text: "connecting text"}

it allows a feature in mermaid to add connecting text like here
This breaks the ability to define a graph via a simple Path array - Path could be redefined as an ordered array of Edges

Update deprecated `deno fmt` options in `deno.json`

See: https://deno.com/blog/v1.33#flatter-denojson-configuration

Current output of deno fmt:

Enable testing for MacOS in CI

Currently there are issues only with md/script/evalCodeBlocks.ts when using Deno.consoleSize() in CI.

Add utilities for codegen in markdown files

See: Markdown Magic

Basically, we want some utility function that finds special pairs of HTML comments in MD files then provides a standard way to run corresponding code and replace the contents between the comment pairs with the code output.

We could use this, for example, to keep the script help text or examples in sync between script files and readmes.

`git/commit/getSpan` JSDoc is incorrect

See: 66cf7c4

Consider removing documentation from readme

After #65 and #66, it may be preferable to simply point to the deno.land/x/ docs page. This would alleviate the need to separately keep the readme and JSDocs up-to-date.

This does raise a new question about the readme's purpose. It might want to house some flashy examples.

Implement simple test coverage assertion script

deno test can generate coverage reports, which can be surfaced with deno coverage. Here are the official docs, and here is an example:

deno test --coverage=some-directory
deno coverage some-directory

This shows the % of lines covered by unit tests, and which specific lines aren't covered, guiding us to places where we can add new unit tests.

Note: unfortunately there are no ignore comments at this time, so we won't be able to correct issues in the coverage report.

See: denoland/deno#16626

The coverage output also supports a common format lcov which various external services like codecov can hook into. However I am also familiar with a great API in Jest, the popular Node.js unit testing framework, which allows the CLI to error if the coverage doesn't meet certain configurable criteria such as total % coverage. We should look into writing a script which allows us to make the similar assertions from Deno's standard coverage outputs. Example:

deno run -A https://deno.land/x/handy/deno/script/assertCoverage.ts \
  coverage-dir --lines=80 # 80% of lines must be covered or this will error

This would be awesome for a CI check without integrating with a 3rd party service and would be an excellent addition to the toolkit.

Add JSDoc comments to all exports

At least include an @example. Things should ideally be named such that their purposes are clear, so we shouldn't mandate that each function and argument has an explanation. But everything can benefit from a copy-pastable example.

Add JSDoc comments to all entry point files

mod.ts, utils.ts, types.ts, scripts.ts

Use @module tag to make them appear in deno.land/x/ and import Intellisense.

Add option for `evalCodeBlocks` to evaluate imports only

Function evalCodeBlocks() should expose importsOnly boolean option which defaults to false
```
evalCodeBlocks(markdown, { importsOnly: true })
```

CLI script evalCodeBlocks should expose --imports-only boolean flag.

deno run handy/md/script/evalCodeBlocks ./readme.md --imports-only

Code block info string should support eval-imports-only option after the language code.

```ts eval-imports-only
import { ThisBetterExist } from "some/where.ts"

// someExpensiveOperation I want to skip...
```

Add CONTRIBUTING.md

brief explanation of folder structure
commit conventions

See: https://contributing.md/example/

`git/script/makeReleaseNotes` should be able to include the starting commit

See: 87f8257

This will make is easier to generate release notes previews for PRs.

`evalCodeBlocks` should parse data formats supported by Deno `std`

The standard library (std) supports:

JSON
JSONC
YAML
TOML
CSV

Add utilities to render `DirectedGraph` as Mermaid chart

Example 1 - Mindmap

mindmap
Root
    A
      B
      C

Example 2 - State Diagram

---
title: Simple sample
---
stateDiagram-v2
    [*] --> Still
    Still --> [*]

    Still --> Moving
    Moving --> Still
    Moving --> Crash
    Crash --> [*]

GitHub Actions steps with `continue-on-error` report as successful even if they fail

See:

test(cli/cmd): Error output mismatch on Linux

Script to surface TODO comments

todo/script/someScriptName.ts <glob> <flags>

# example
todo/script/someScriptName.ts **/*.ts # list them in stdout
todo/script/someScriptName.ts **/*.ts -t # throw if any are found

Add `file/handler`

Both some of the glob utilities and the markdown code block eval utilities would benefit from a standard interface for reading, writing, and evaluating files by file type.

`evalCodeBlocks` should execute blocks in parallel and display loading indicators

This should make the script much faster and provide more useful feedback.

Add `git/commit/lint` and `git/script/commitlint`

We don't need full parity with the original but we should take inspiration from its configuration options.

extract `offset()` helper from `location()`

This functionality is independently useful, has helpful error messages, and conveys a common concept succinctly. Further exploration revealed this has uses beyond strings - arrays and typed arrays can also benefit, so the function should be placed in the collections module which exists for such generic purposes.

`git/script/makeReleaseNotes` should be able to include conventional commit footers

See: 87f8257

This would allow TODO items to appear in release notes previews in PRs, as well as common footers like BREAKING CHANGE and refs.

Might want this to be on by default, possibly even on and non-configurable. Arguably a bug that these are presently omitted.

Fix readme tests in linux

See: https://github.com/pskfyi/handy/actions/runs/4878230595/jobs/8703685166?pr=46

`path/utils` should export `dir`

This was an oversight which is causing issues in the "test-readme" task and #58.

TODO comment parser

Useful for identifying if a file has such comments, and for extracting the contents of those comments where they could then be aggregated into a checklist or unordered list.

Probably deserves a top-level todo module.

`evalCodeBlocks` should log the full file path w/ line number of each failed evaluation

This will allow users to ctrl+click / cmd+click on the path to jump to the relevant code block

`evalCodeBlocks` should return a non-zero exit code if any code blocks errored

Currently it always returns exit code 0.

Add JSDoc parser

`evalCodeBlocks` should accept configuration from an HTML comment within the input markdown

This would allow individual markdown files to contain their own find/replace strings, register language handlers, and other configurations. Here is a concept for discussion purposes:

<!--config:evalCodeBlocks:yaml

  fileHandler:
    py: "./python/evaulate.ts"
  replace:
  - ["hello", "goodbye"]
  - ["world", "mars"]
-->
  
```py
print("hello world!")
```

import { evalCodeBlocks } from "./handy/md/script/evalCodeBlocks.ts"

const markdown = Deno.readTextFileSync("./myFile.md") // the file above with the HTML comment

const results = evalCodeBlocks(markdown)

assert(results[0] === "goodbye mars")

Enable `deno task test-readme` in CI

Blocked by

Add utilities to render `DirectedGraph` as an ASCII tree

Create string/location utility

from PR #76

io/clipboard on linux: command fails if xclip is not installed

Maybe we can add (error output includes "File not found")?:include "apt-get install xclip" in error output

Enable testing for Windows in CI

Currently there are multiple issues. May need to be addressed across multiple PRs.

`evalCodeBlocks` should handle JSX and TSX

See: https://deno.land/manual/jsx_dom/jsx

Individual code blocks should be able to opt out of `evalCodeBlocks`

We should check the info string of fenced blocks for no-eval after the language code, and if present skip evaluation of those blocks.

  ```ts no-eval
  // won't be evaluated
  ```

`evalCodeBlocks` should handle JS

Currently it only handles TS

Enable testing for Linux in CI

Issues currently unknown. Needs triaging.

Add JSDoc linter

Investigate making our GitHub Actions PR workflow reusable

See: https://docs.github.com/en/actions/using-workflows/reusing-workflows

Add utilities for codegen in JSDoc comments

Same as #68 but for JSDoc comments. This can help us manage #65.

Preview release notes for commits in a PR

Investigate leveraging git/script/makeReleaseNotes.ts to create or update a comment in the PR which contains the generated release notes for all commits in the PR, surrounded by a <details> element. All commits should be shown, even commits which typically would not be included in Handy's release notes such as refactor commits.

This would be useful to ensure that Markdown in conventional commit bodies are as desired before being merged.