feat: added docs

Signed-off-by: mbwhite <[email protected]>

README.md

@@ -4,12 +4,29 @@
 
 ## Quick Start 
 
-Using Node 20 or later:
+Using the latest v1 tekton-lint and Node 18 or later....
 
 ```
-npx @ibm/tekton-lint <glob-pattern-to-yaml-files>
+npx @ibm/tekton-lint@latest <glob-pattern-to-yaml-files>
 ```
 
+> (v1 is currently in alpha)
+
+To try a quick example, grab the `example-task.yaml` from this repo
+
+```sh
+> wget https://raw.githubusercontent.com/IBM/tekton-lint/main/example-task.yaml
+> npx @ibm/tekton-lint@latest  example-task.yaml
+
+example-task.yaml
+   4:9   error    Invalid name for Task 'Task-without-params'. Names should be in lowercase, alphanumeric, kebab-case format  no-invalid-name
+  10:14  warning  Invalid image: 'busybox'. Specify the image tag instead of using ':latest'                                  no-latest-image
+   9:31  error    Undefined param 'contextDir' at .spec.steps[0].command[2] in 'Task-without-params'                          no-undefined-param
+  11:19  error    Undefined param 'contextDir' at .spec.steps[0].workingDir in 'Task-without-params'                          no-undefined-param
+
+✖ 4 problems (3 errors, 1 warning)
+
+```
 
 ## Usage
 
@@ -20,6 +37,8 @@ on the resulting document set. [More details on the pattern syntax.][pattern]
 
 Using `tekton-lint` in watch mode will monitor for any changes in the provided paths and automatically run the linter again.
 
+Be mindful if you specify a glob pattern (eg `*.yaml`) that this might be expanded by your shell rather than the tool itself. It'll probably be fine for the vast majority of cases.  
+
 ```sh
 tekton-lint [<options>]  <glob-pattern-to-yaml-files> ...
 
@@ -48,6 +67,8 @@ Examples:
 
 ### IDE Integration
 
+> note this is hasn't been extensively tested yet in alpha - focussing on the cli invocation
+
 `tekton-lint` can be added as a [Task][vscode-task]:
 
 ```js
@@ -62,6 +83,8 @@ Examples:
       "command": "tekton-lint",
       "args": [
         "--watch",
+        "--format","vscode",
+        "--config","${workspaceFolder}/.vscode/.tektonlintrc.yaml",  // if needed, otherwise remove this line
         "${workspaceFolder}/**/*.yaml" // Change this path to the path of your yaml files (this will watch for every yaml file in your currently open workspace)
       ],
       "problemMatcher": [
@@ -98,6 +121,8 @@ You can run this task from _Terminal_ > _Run Task..._ > _Run tekton-lint_:
 
 ### API
 
+> note this is hasn't been extensively tested yet in alpha - focussing on the cli invocation
+
 #### `linter(globs: string[], config?: Config): Promise<Problem[]>`
 
 Runs the linter on the provided `globs`, and resolves to the list of found problems.
@@ -224,13 +249,19 @@ for (const problem of problems) {
 
 ### Configuring `tekton-lint`
 
-You can configure `tekton-lint` with a configuration file ([`.tektonlintrc.yaml`](./.tektonlintrc.yaml)) in your project's directory. You can decide which rules are enabled and at what error level.
+You can configure `tekton-lint` with a configuration file ([`.tektonlintrc.yaml`](./.tektonlintrc.yaml)).  You can decide which rules are enabled and at what error level. In addition you can specify external tekton tasks defined in a git repository; for example [OpenToolChain](https://github.com/open-toolchain/tekton-catalog) provides a set of tasks that are helpful. But if you lint just your own tekton files there will be errors about not being able to find `git-clone-repo` for example. Not will any checks be made to see if your usage is correct.
+
+Any task defined in the `external-tasks` section will be clone from git, into a local cache (defaults to `~/.tektonlint`).  Please make sure that you can `git clone` before running.
 
 The configuration file should follow this format:
 ```yaml
 ---
 rules:
   rule-name: error | warning | off
+external-tasks:
+  - name: <tasks name>
+    uri: http://github.com/....
+    path: <sub dir of repo>
 ```
 
 Example `.tektonlintrc.yaml` file:
@@ -241,9 +272,31 @@ rules:
   no-duplicate-param: error
   no-unused-param: warning
   no-deprecated-resource: off
+external-tasks:
+  - name: git-clone-repo
+    uri: https://github.com/open-toolchain/tekton-catalog
+    path: git
+  - name: toolchain-extract-value
+    uri: https://github.com/open-toolchain/tekton-catalog
+    path: toolchain
+  - name: doi-publish-build-record
+    uri: https://github.com/open-toolchain/tekton-catalog
+    path: devops-insights    
+  - name: icr-publish
+    uri: https://github.com/open-toolchain/tekton-catalog
+    path: container-registry
+  - name: iks-detch
+    uri: https://github.com/open-toolchain/tekton-catalog
+    path: kubernetes-service  
+
 ```
 
-`tekton-lint` will look for a configuration file named `.tektonlintrc.yaml` in the directory where you run the command. If the configuration file is not present, `tekton-lint` will use the default configuration.
+Search path for `.tektonlintrc.yaml`
+
+- location specified on the command line with the `--config` option
+- current working directory
+- default values used if nothing else found
+
 
 [tekton]: https://tekton.dev
 [node]: https://nodejs.org

example-task.yaml

@@ -0,0 +1,14 @@
+apiVersion: tekton.dev/v1beta1
+kind: Task
+metadata:
+  name: Task-without-params
+spec:
+  params: []
+  steps:
+    - name: ls-build-sources
+      command: ["ls", "-ltr", "/workspace/source/$(params.contextDir)"]
+      image: busybox
+      workingDir: /workspace/source/$(params.contextDir)
+  workspaces:
+    - description: The git repo will be cloned onto the volume backing this workspace
+      name: source