asljs-rq-cli 0.0.0-stage → 0.1.2

package/package.json

@@ -1,6 +1,73 @@
 {
   "name": "asljs-rq-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.2",
+  "description": "The rq command line over asljs-rq: query, change, check, test and view requirements.",
+  "type": "module",
+  "asljs": {
+    "type": "app"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/**",
+    "bin/**",
+    "docs/**",
+    "skills/*.md",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "bin": {
+    "rq": "bin/rq.js"
+  },
+  "scripts": {
+    "flint": "toolkit flint",
+    "clean": "toolkit clean",
+    "build": "npm run codegen --if-present && tsc -p tsconfig.build.json",
+    "build:dist": "npm run codegen --if-present && tsc -p tsconfig.dist.json",
+    "typecheck": "npm run codegen --if-present && tsc -p tsconfig.build.json --noEmit",
+    "guard:clean-git": "toolkit ensure-clean-working-directory",
+    "prepack": "npm run clean && npm run build:dist && npm run build && npm run test && npm run guard:clean-git",
+    "postpublish": "toolkit tag-release-revision",
+    "test": "node --test --enable-source-maps \"build/**/*.test.js\"",
+    "test:watch": "node --watch --test \"build/**/*.test.js\"",
+    "release:patch": "toolkit release-patch",
+    "all": "npm run clean && npm run build:dist && npm run flint && npm run typecheck && npm run build && npm run test"
+  },
+  "keywords": [
+    "requirements",
+    "traceability",
+    "test",
+    "markdown",
+    "ai",
+    "cli"
+  ],
+  "homepage": "https://github.com/AlexandriteSoftware/asljs#readme",
+  "bugs": {
+    "url": "https://github.com/AlexandriteSoftware/asljs/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AlexandriteSoftware/asljs.git"
+  },
+  "author": "\"Alex Netkachov\" <alex.netkachov@gmail.com>",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "dependencies": {
+    "asljs-agents": "^0.1.0",
+    "asljs-logging": "^0.1.2",
+    "asljs-mdcli": "^0.1.3",
+    "asljs-rq": "^0.1.6",
+    "asljs-rq-srv": "^0.1.1",
+    "commander": "^15.0.0"
+  },
+  "devDependencies": {
+    "asljs-testing": "^0.1.0",
+    "asljs-tmpdir": "^0.1.13",
+    "asljs-toolkit": "^0.1.0"
+  }
+}

package/skills/requirements-authoring.md

@@ -0,0 +1,82 @@
+# requirements-authoring
+
+Use when: writing a requirement, decomposing one into smaller requirements, or
+writing the test that shows a requirement holds.
+
+The formats and the rules every change keeps are in [Requirement files][RF], and
+what `rq` does with them in [Requirements][RM]. Requirements (`R<n> <name>.md`)
+and tests (`T<n> <name>.md`) are the nodes of one graph, and the links in each
+requirement's `## Implementation` list are its edges. A requirement nothing
+links to is a root; every other requirement is linked from exactly one
+requirement, and every test from at least one. Other documents, and links in a
+statement, are references the graph ignores.
+
+## Text and structure
+
+- Edit text directly: the statement of a requirement, the description and the
+  `## Steps` of a test, and any section the commands do not own.
+- Change the structure only with the [commands][CG]: `rq add requirement`, `rq
+  add test`, `rq link`, `rq unlink`, `rq move`, `rq remove` and `rq log`. Do not
+  add, change or remove links to requirements or tests, files, `##
+  Implementation` items, results or `## Status` sections by editing the text.
+- Read the structure with `rq links`, `rq backlinks`, `rq list` and `rq tojson`
+  rather than by searching the text; `--json` gives a stable shape.
+
+## Writing a requirement
+
+1. State what must be true of the system, not how it is built. One idea per
+   statement, each one checkable.
+2. Create it under the requirement it helps implement: `rq add requirement
+   <parent> "<name>" --statement "<statement>"`. The command picks the id, names
+   the file, and links it from the parent.
+3. Refine the statement by editing the text when it needs more than a line.
+
+## Decomposing
+
+A requirement is too big for a test when no single, short set of commands can
+show that it holds.
+
+1. List its statements.
+2. Group them into smaller requirements, each with a narrower scope; a statement
+   may also be covered directly by a test.
+3. Create each with `rq add requirement` or `rq add test`, or link an existing
+   one with `rq link`.
+4. Check coverage: every statement is implemented by at least one link. Unlink
+   what implements no statement with `rq unlink`.
+5. `rq link` refuses a link back up the graph, and a second parent for a
+   requirement: link an existing requirement only when it has no parent yet. A
+   test may be linked from every requirement it checks. Links in a test are not
+   edges, so a test may refer to what it checks, but does not have to.
+
+## Writing a test
+
+1. Create it: `rq add test <requirement> "<name>" --description "<what it
+   shows>" --step "<command>"`, one `shell` step per `--step`.
+2. Each step is a `###` heading under `## Steps`. Edit the text to use another
+   type: `- Type: javascript` with `- File:` and `- Test:`, `- Type: dotnet`
+   with `- Project:` and `- Filter:`, or plain text for an instruction an AI
+   agent carries out. Prefer the typed steps; an instruction is for what no
+   command can check.
+3. Steps run in the test's folder, so use paths relative to it, or `cd` within a
+   shell line.
+4. Make the steps deterministic and reproducible: no network services, clocks or
+   random data the steps do not control, and no manual actions. Prefer running
+   an existing test filtered to the behavior, e.g. `npm test --
+   --test-name-pattern="..."`.
+5. `rq test <test>` runs it and records the result in `.rq/E<n> <slug>.md`.
+   Record a result established another way with `rq log <test> --result
+   PASS|FAIL --note "<how>"`.
+
+## Checking
+
+Run `rq check <path>` after every change, then `rq test <id> --recurse` on the
+changed subtree, and `rq coverage <id> --recurse` when the decomposition
+changed, so that an agent checks coverage. Fix what they report before
+finishing; [requirements-coverage][RC] says how to act on the `## Coverage`
+analysis of an incomplete requirement.
+
+[RC]: requirements-coverage.md
+
+[CG]: <../docs/Changing the graph.md>
+[RF]: <../../rq/docs/Requirement files.md>
+[RM]: ../../rq/docs/Requirements.md

package/skills/requirements-change.md

@@ -0,0 +1,51 @@
+# requirements-change
+
+Use when: a requirement was added, changed or removed, or the behavior a test
+shows changed, and the related requirements must be brought in line.
+
+The formats and the rules every change keeps are in [Requirement files][RF], and
+what `rq` does with them in [Requirements][RM]; how to write the documents, and
+which changes go through the commands, is in [requirements-authoring][RA].
+
+## Find the related nodes
+
+For the changed requirement:
+
+- parents - `rq backlinks <file> --json`;
+- children - `rq links <file> --json`;
+- siblings - `rq links` of each parent: the other children, which may now
+  overlap with it or leave a gap.
+
+## Update them
+
+1. Parents: check that their statements are still fully covered. When the change
+   narrowed the requirement, cover the rest with another requirement or test
+   (`rq add requirement`, `rq add test`, `rq link`); when it widened it, narrow
+   the text of the parent or a sibling so that no statement is implemented twice
+   in contradicting ways.
+2. Children: check that each still implements a statement of the changed
+   requirement. Edit the text of the ones that implement an old statement, `rq
+   unlink` the ones that implement none, and add requirements or tests for
+   statements nothing covers.
+3. Test: when the behavior changed, edit the steps so that they show the new
+   behavior. Leave the results to `rq test` and `rq log`.
+4. Repeat for every node that changed, until a pass changes nothing.
+5. A removed requirement: `rq remove <file>`, with `--recursive` to remove what
+   only it links to, then check its former parents as in step 1.
+6. A renamed or moved requirement: `rq move <file> <destination>`, which
+   rewrites the links to it.
+
+## Verify
+
+Run `rq check`, then `rq test <path>` and `rq coverage <path>` on the roots, or
+`rq test <id> --recurse` and `rq coverage <id> --recurse` on the highest
+requirement that changed. Every structure error, failed test and uncovered
+statement is a remaining inconsistency; fix it or report it with the reason. For
+an incomplete coverage, follow [requirements-coverage][RC], which works from the
+analysis in the requirement's `## Coverage` section.
+
+[RC]: requirements-coverage.md
+
+[RA]: requirements-authoring.md
+[RF]: <../../rq/docs/Requirement files.md>
+[RM]: ../../rq/docs/Requirements.md

package/skills/requirements-coverage.md

@@ -0,0 +1,48 @@
+# requirements-coverage
+
+Use when: checking whether requirements are fully covered, or closing the gaps
+`rq coverage` reports - a requirement whose `Coverage` is `INCOMPLETE`.
+
+The formats and the rules every change keeps are in [Requirement files][RF], and
+what `rq` does with them in [Requirements][RM]; how to write requirements and
+tests, and which changes go through the commands, is in
+[requirements-authoring][RA].
+
+## Check
+
+1. Run `rq coverage <id> --recurse` on the highest requirement that changed, or
+   `rq coverage <folder>` for all. An agent judges each requirement and records
+   the verdict in `- Coverage:` of its `## Status`, and the reasons in its `##
+   Coverage` section. It costs one agent call per requirement, so check what
+   changed rather than everything.
+2. List what is left: `rq list <folder> --json`, the requirements whose
+   `coverage` is `INCOMPLETE` or `null` (never checked).
+
+## Close a gap
+
+For each incomplete requirement, read its `## Coverage` section: it names each
+statement nothing covers and what would cover it. Then, as it suggests:
+
+- a missing test - `rq add test <requirement> "<name>" --description "<what it
+  shows>"` with steps that check exactly the uncovered statement, then `rq test
+  <test>`;
+- a missing sub-requirement - `rq add requirement <requirement> "<name>"
+  --statement "<statement>"`, then cover the new requirement in turn;
+- an existing requirement or test that covers it but is not linked - `rq link
+  <requirement> <node>`, keeping one parent per requirement;
+- a statement no one should implement, or one stated twice - edit the
+  requirement's text so that it says what is meant.
+
+Do not edit `## Coverage` or `## Status` by hand: `rq coverage` rewrites both.
+Re-run `rq coverage <id>` on the requirement, and `rq test <id> --recurse` when
+tests were added, until it is `COMPLETE`.
+
+## Read a complete verdict
+
+A `COMPLETE` requirement's `## Coverage` says which link covers each statement.
+Use it to review the decomposition: a link that covers no statement can be
+unlinked, and a statement covered only by a vague test deserves a sharper one.
+
+[RA]: requirements-authoring.md
+[RF]: <../../rq/docs/Requirement files.md>
+[RM]: ../../rq/docs/Requirements.md