@dxos/deus 0.0.0-stage → 0.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +105 -0
- package/README.md +24 -2
- package/bin/deus.ts +42 -0
- package/dist/lib/chunk-blocks.mjs +151 -0
- package/dist/lib/chunk-blocks.mjs.map +1 -0
- package/dist/lib/chunk-check.mjs +452 -0
- package/dist/lib/chunk-check.mjs.map +1 -0
- package/dist/lib/chunk-completion.mjs +112 -0
- package/dist/lib/chunk-completion.mjs.map +1 -0
- package/dist/lib/chunk-extension.mjs +396 -0
- package/dist/lib/chunk-extension.mjs.map +1 -0
- package/dist/lib/chunk-parse.mjs +21 -0
- package/dist/lib/chunk-parse.mjs.map +1 -0
- package/dist/lib/cli.mjs +946 -0
- package/dist/lib/cli.mjs.map +1 -0
- package/dist/lib/extension.mjs +4 -0
- package/dist/lib/index.mjs +6 -0
- package/dist/lib/parse.mjs +4 -0
- package/dist/lib/review.mjs +260 -0
- package/dist/lib/review.mjs.map +1 -0
- package/dist/lib/spec-index.mjs +28 -0
- package/dist/lib/spec-index.mjs.map +1 -0
- package/dist/types/bin/deus.d.ts +3 -0
- package/dist/types/bin/deus.d.ts.map +1 -0
- package/dist/types/src/cli/__fixtures__/review/plugin-deps/dx.config.d.ts +8 -0
- package/dist/types/src/cli/__fixtures__/review/plugin-deps/dx.config.d.ts.map +1 -0
- package/dist/types/src/cli/__fixtures__/review/plugin-deps-diverged/dx.config.d.ts +8 -0
- package/dist/types/src/cli/__fixtures__/review/plugin-deps-diverged/dx.config.d.ts.map +1 -0
- package/dist/types/src/cli/__fixtures__/review/plugin-deps-empty/dx.config.d.ts +7 -0
- package/dist/types/src/cli/__fixtures__/review/plugin-deps-empty/dx.config.d.ts.map +1 -0
- package/dist/types/src/cli/__fixtures__/review/plugin-deps-mismatch/dx.config.d.ts +8 -0
- package/dist/types/src/cli/__fixtures__/review/plugin-deps-mismatch/dx.config.d.ts.map +1 -0
- package/dist/types/src/cli/__fixtures__/review/plugin-deps-noplugin/dx.config.d.ts +5 -0
- package/dist/types/src/cli/__fixtures__/review/plugin-deps-noplugin/dx.config.d.ts.map +1 -0
- package/dist/types/src/cli/changelog.d.ts +25 -0
- package/dist/types/src/cli/changelog.d.ts.map +1 -0
- package/dist/types/src/cli/cli.test.d.ts +2 -0
- package/dist/types/src/cli/cli.test.d.ts.map +1 -0
- package/dist/types/src/cli/errors.d.ts +183 -0
- package/dist/types/src/cli/errors.d.ts.map +1 -0
- package/dist/types/src/cli/features.d.ts +58 -0
- package/dist/types/src/cli/features.d.ts.map +1 -0
- package/dist/types/src/cli/git.d.ts +8 -0
- package/dist/types/src/cli/git.d.ts.map +1 -0
- package/dist/types/src/cli/index.d.ts +12 -0
- package/dist/types/src/cli/index.d.ts.map +1 -0
- package/dist/types/src/cli/lint.d.ts +17 -0
- package/dist/types/src/cli/lint.d.ts.map +1 -0
- package/dist/types/src/cli/qa-lint.d.ts +40 -0
- package/dist/types/src/cli/qa-lint.d.ts.map +1 -0
- package/dist/types/src/cli/qa.d.ts +86 -0
- package/dist/types/src/cli/qa.d.ts.map +1 -0
- package/dist/types/src/cli/review.d.ts +38 -0
- package/dist/types/src/cli/review.d.ts.map +1 -0
- package/dist/types/src/cli/spec-index.d.ts +17 -0
- package/dist/types/src/cli/spec-index.d.ts.map +1 -0
- package/dist/types/src/extension/blocks.d.ts +65 -0
- package/dist/types/src/extension/blocks.d.ts.map +1 -0
- package/dist/types/src/extension/check.d.ts +99 -0
- package/dist/types/src/extension/check.d.ts.map +1 -0
- package/dist/types/src/extension/check.test.d.ts +2 -0
- package/dist/types/src/extension/check.test.d.ts.map +1 -0
- package/dist/types/src/extension/code.d.ts +7 -0
- package/dist/types/src/extension/code.d.ts.map +1 -0
- package/dist/types/src/extension/complete.d.ts +6 -0
- package/dist/types/src/extension/complete.d.ts.map +1 -0
- package/dist/types/src/extension/completion.d.ts +10 -0
- package/dist/types/src/extension/completion.d.ts.map +1 -0
- package/dist/types/src/extension/constants.d.ts +6 -0
- package/dist/types/src/extension/constants.d.ts.map +1 -0
- package/dist/types/src/extension/fences.d.ts +10 -0
- package/dist/types/src/extension/fences.d.ts.map +1 -0
- package/dist/types/src/extension/gen/mdl.d.ts +3 -0
- package/dist/types/src/extension/gen/mdl.d.ts.map +1 -0
- package/dist/types/src/extension/gen/mdl.terms.d.ts +2 -0
- package/dist/types/src/extension/gen/mdl.terms.d.ts.map +1 -0
- package/dist/types/src/extension/index.d.ts +8 -0
- package/dist/types/src/extension/index.d.ts.map +1 -0
- package/dist/types/src/extension/language.d.ts +20 -0
- package/dist/types/src/extension/language.d.ts.map +1 -0
- package/dist/types/src/extension/lint.d.ts +8 -0
- package/dist/types/src/extension/lint.d.ts.map +1 -0
- package/dist/types/src/extension/parse.d.ts +6 -0
- package/dist/types/src/extension/parse.d.ts.map +1 -0
- package/dist/types/src/extension/parser.test.d.ts +2 -0
- package/dist/types/src/extension/parser.test.d.ts.map +1 -0
- package/dist/types/src/extension/refs.d.ts +32 -0
- package/dist/types/src/extension/refs.d.ts.map +1 -0
- package/dist/types/src/extension/refs.test.d.ts +2 -0
- package/dist/types/src/extension/refs.test.d.ts.map +1 -0
- package/dist/types/src/extension/syntax.d.ts +12 -0
- package/dist/types/src/extension/syntax.d.ts.map +1 -0
- package/dist/types/src/index.d.ts +3 -0
- package/dist/types/src/index.d.ts.map +1 -0
- package/dist/types/src/review/fields.d.ts +9 -0
- package/dist/types/src/review/fields.d.ts.map +1 -0
- package/dist/types/src/review/index.d.ts +5 -0
- package/dist/types/src/review/index.d.ts.map +1 -0
- package/dist/types/src/review/review.d.ts +70 -0
- package/dist/types/src/review/review.d.ts.map +1 -0
- package/dist/types/src/review/review.test.d.ts +2 -0
- package/dist/types/src/review/review.test.d.ts.map +1 -0
- package/dist/types/src/review/source-key.d.ts +35 -0
- package/dist/types/src/review/source-key.d.ts.map +1 -0
- package/dist/types/src/review/symbol.d.ts +17 -0
- package/dist/types/src/review/symbol.d.ts.map +1 -0
- package/dist/types/src/review/symbol.test.d.ts +2 -0
- package/dist/types/src/review/symbol.test.d.ts.map +1 -0
- package/dist/types/src/spec-index/index.d.ts +3 -0
- package/dist/types/src/spec-index/index.d.ts.map +1 -0
- package/dist/types/src/spec-index/parse.d.ts +11 -0
- package/dist/types/src/spec-index/parse.d.ts.map +1 -0
- package/dist/types/src/spec-index/spec-index.d.ts +21 -0
- package/dist/types/src/spec-index/spec-index.d.ts.map +1 -0
- package/dist/types/src/spec-index/spec-index.test.d.ts +2 -0
- package/dist/types/src/spec-index/spec-index.test.d.ts.map +1 -0
- package/dist/types/tsconfig.tsbuildinfo +1 -0
- package/docs/DESIGN.md +561 -0
- package/docs/IDIOMS.md +265 -0
- package/lang/PLUGIN-.template.mdl +115 -0
- package/lang/app.mdl +200 -0
- package/lang/changelog.mdl +184 -0
- package/lang/core.mdl +203 -0
- package/lang/examples/chess-1.mdl +149 -0
- package/lang/examples/chess-2.mdl +203 -0
- package/lang/examples/chess-3.mdl +231 -0
- package/lang/features.mdl +92 -0
- package/lang/plugin.mdl +59 -0
- package/lang/qa.mdl +383 -0
- package/lang/review.mdl +103 -0
- package/lang/sql.mdl +72 -0
- package/package.json +74 -3
- package/src/cli/__fixtures__/bad-decision.mdl +13 -0
- package/src/cli/__fixtures__/features/CYCLE.mdl +25 -0
- package/src/cli/__fixtures__/features/FEATURES.mdl +47 -0
- package/src/cli/__fixtures__/features/SPEC.mdl +22 -0
- package/src/cli/__fixtures__/features/SPEC.review.mdl +32 -0
- package/src/cli/__fixtures__/features/TASKS.md +5 -0
- package/src/cli/__fixtures__/lint-refs/SPEC.mdl +7 -0
- package/src/cli/__fixtures__/lint-refs/SPEC.review.mdl +7 -0
- package/src/cli/__fixtures__/qa-lint/packages/plugins/plugin-risky/PLUGIN.mdl +29 -0
- package/src/cli/__fixtures__/qa-list/plugin-sample/spec/PLUGIN.mdl +51 -0
- package/src/cli/__fixtures__/review/SPEC.mdl +23 -0
- package/src/cli/__fixtures__/review/SPEC.review.mdl +26 -0
- package/src/cli/__fixtures__/review/plugin-deps/PLUGIN.mdl +9 -0
- package/src/cli/__fixtures__/review/plugin-deps/PLUGIN.review.mdl +13 -0
- package/src/cli/__fixtures__/review/plugin-deps/dx.config.ts +10 -0
- package/src/cli/__fixtures__/review/plugin-deps-diverged/PLUGIN.mdl +9 -0
- package/src/cli/__fixtures__/review/plugin-deps-diverged/PLUGIN.review.mdl +14 -0
- package/src/cli/__fixtures__/review/plugin-deps-diverged/dx.config.ts +10 -0
- package/src/cli/__fixtures__/review/plugin-deps-empty/PLUGIN.mdl +9 -0
- package/src/cli/__fixtures__/review/plugin-deps-empty/PLUGIN.review.mdl +13 -0
- package/src/cli/__fixtures__/review/plugin-deps-empty/dx.config.ts +9 -0
- package/src/cli/__fixtures__/review/plugin-deps-mismatch/PLUGIN.mdl +9 -0
- package/src/cli/__fixtures__/review/plugin-deps-mismatch/PLUGIN.review.mdl +13 -0
- package/src/cli/__fixtures__/review/plugin-deps-mismatch/dx.config.ts +10 -0
- package/src/cli/__fixtures__/review/plugin-deps-noplugin/PLUGIN.mdl +9 -0
- package/src/cli/__fixtures__/review/plugin-deps-noplugin/PLUGIN.review.mdl +13 -0
- package/src/cli/__fixtures__/review/plugin-deps-noplugin/dx.config.ts +7 -0
- package/src/cli/changelog.ts +122 -0
- package/src/cli/cli.test.ts +359 -0
- package/src/cli/errors.ts +23 -0
- package/src/cli/features.ts +320 -0
- package/src/cli/git.ts +35 -0
- package/src/cli/index.ts +27 -0
- package/src/cli/lint.ts +75 -0
- package/src/cli/qa-lint.ts +206 -0
- package/src/cli/qa.ts +300 -0
- package/src/cli/review.ts +359 -0
- package/src/cli/spec-index.ts +54 -0
- package/src/extension/blocks.ts +169 -0
- package/src/extension/check.test.ts +629 -0
- package/src/extension/check.ts +552 -0
- package/src/extension/code.ts +99 -0
- package/src/extension/complete.ts +34 -0
- package/src/extension/completion.ts +64 -0
- package/src/extension/constants.ts +28 -0
- package/src/extension/fences.ts +270 -0
- package/src/extension/gen/mdl.terms.ts +16 -0
- package/src/extension/gen/mdl.ts +16 -0
- package/src/extension/index.ts +25 -0
- package/src/extension/language.ts +33 -0
- package/src/extension/lint.ts +19 -0
- package/src/extension/mdl.grammar +60 -0
- package/src/extension/parse.ts +31 -0
- package/src/extension/parser.test.ts +248 -0
- package/src/extension/refs.test.ts +95 -0
- package/src/extension/refs.ts +94 -0
- package/src/extension/syntax.ts +25 -0
- package/src/index.ts +6 -0
- package/src/review/fields.ts +31 -0
- package/src/review/index.ts +8 -0
- package/src/review/review.test.ts +111 -0
- package/src/review/review.ts +184 -0
- package/src/review/source-key.ts +63 -0
- package/src/review/symbol.test.ts +47 -0
- package/src/review/symbol.ts +96 -0
- package/src/spec-index/index.ts +6 -0
- package/src/spec-index/parse.ts +22 -0
- package/src/spec-index/spec-index.test.ts +56 -0
- package/src/spec-index/spec-index.ts +49 -0
package/dist/lib/cli.mjs
ADDED
|
@@ -0,0 +1,946 @@
|
|
|
1
|
+
import { r as reqs, t as frontmatter } from "./chunk-parse.mjs";
|
|
2
|
+
import { o as parseMdlBlocks } from "./chunk-blocks.mjs";
|
|
3
|
+
import { a as lintMdl, n as checkChangelogChange, p as specDependencies } from "./chunk-check.mjs";
|
|
4
|
+
import { indexSpecs, isIndexedSpec } from "./spec-index.mjs";
|
|
5
|
+
import * as Command from "effect/cli/Command";
|
|
6
|
+
import * as Flag from "effect/cli/Flag";
|
|
7
|
+
import * as Config from "effect/Config";
|
|
8
|
+
import * as Console from "effect/Console";
|
|
9
|
+
import * as Effect from "effect/Effect";
|
|
10
|
+
import * as FileSystem from "effect/FileSystem";
|
|
11
|
+
import * as Path from "effect/Path";
|
|
12
|
+
import { BaseError } from "@dxos/errors";
|
|
13
|
+
import * as ChildProcess from "effect/process/ChildProcess";
|
|
14
|
+
import * as ChildProcessSpawner from "effect/process/ChildProcessSpawner";
|
|
15
|
+
import * as Stream from "effect/Stream";
|
|
16
|
+
import * as Argument from "effect/cli/Argument";
|
|
17
|
+
import * as Option from "effect/Option";
|
|
18
|
+
import * as Context from "effect/Context";
|
|
19
|
+
//#region src/cli/errors.ts
|
|
20
|
+
/** A git command failed or exited non-zero. */
|
|
21
|
+
var GitError = class extends BaseError.extend("DeusGitError", "A git command failed.") {};
|
|
22
|
+
/** One or more changed specs break the changelog rules. */
|
|
23
|
+
var ChangelogCheckError = class extends BaseError.extend("DeusChangelogCheckError", "Spec changelog check failed.") {};
|
|
24
|
+
/** A QA lint reported findings in the plugin specs. */
|
|
25
|
+
var QaLintError = class extends BaseError.extend("DeusQaLintError", "The QA lints reported findings.") {};
|
|
26
|
+
/** A spec review breaks the review rules. */
|
|
27
|
+
var ReviewCheckError = class extends BaseError.extend("DeusReviewCheckError", "The spec review has errors.") {};
|
|
28
|
+
/** One or more `.mdl` files have lint errors. */
|
|
29
|
+
var LintError = class extends BaseError.extend("DeusLintError", "The .mdl files have lint errors.") {};
|
|
30
|
+
/** The feature map has errors: a bad status, a spec reference that resolves to nothing, or a dependency cycle. */
|
|
31
|
+
var FeatureCheckError = class extends BaseError.extend("DeusFeatureCheckError", "The feature map has errors.") {};
|
|
32
|
+
//#endregion
|
|
33
|
+
//#region src/cli/git.ts
|
|
34
|
+
/** Runs `git <args>` in `cwd` and returns trimmed stdout; a non-zero exit fails with {@link GitError}. */
|
|
35
|
+
var git = Effect.fnUntraced(function* (cwd, ...args) {
|
|
36
|
+
const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
|
|
37
|
+
return yield* Effect.scoped(Effect.gen(function* () {
|
|
38
|
+
const handle = yield* spawner.spawn(ChildProcess.make("git", args, { cwd }));
|
|
39
|
+
const [stdout, stderr, exitCode] = yield* Effect.all([
|
|
40
|
+
Stream.mkString(Stream.decodeText(handle.stdout)),
|
|
41
|
+
Stream.mkString(Stream.decodeText(handle.stderr)),
|
|
42
|
+
handle.exitCode
|
|
43
|
+
], { concurrency: "unbounded" });
|
|
44
|
+
if (exitCode !== 0) return yield* Effect.fail(new GitError({ context: {
|
|
45
|
+
args,
|
|
46
|
+
exitCode,
|
|
47
|
+
stderr: stderr.trim()
|
|
48
|
+
} }));
|
|
49
|
+
return stdout.trim();
|
|
50
|
+
})).pipe(Effect.catchTag("PlatformError", (error) => Effect.fail(new GitError({
|
|
51
|
+
cause: error,
|
|
52
|
+
context: { args }
|
|
53
|
+
}))));
|
|
54
|
+
});
|
|
55
|
+
/** Splits command output into its non-empty lines. */
|
|
56
|
+
var lines = (text) => text.split("\n").filter(Boolean);
|
|
57
|
+
//#endregion
|
|
58
|
+
//#region src/cli/changelog.ts
|
|
59
|
+
/** A commit trailer that waives the missing-decision rule for a bulk mechanical edit; append-only rules still apply. */
|
|
60
|
+
var WAIVER = "Spec-Changelog-Skip";
|
|
61
|
+
/** Language definitions, review rules, spec reviews and test fixtures are .mdl files but not specs. */
|
|
62
|
+
var EXEMPT = [
|
|
63
|
+
/^packages\/reflect\/deus\/lang\//,
|
|
64
|
+
/\/__fixtures__\//,
|
|
65
|
+
/(^|\/)rules\//,
|
|
66
|
+
/\.review\.mdl$/
|
|
67
|
+
];
|
|
68
|
+
var DEFAULT_BASE_REF = "origin/main";
|
|
69
|
+
/**
|
|
70
|
+
* Fails when a changed .mdl spec has no new `## Changelog` decision, or edits the log in place (lang/changelog.mdl).
|
|
71
|
+
* Whitespace and small typo fixes need no decision; a `Spec-Changelog-Skip: <reason>` commit trailer waives the rule.
|
|
72
|
+
* Compares the working tree with the merge base of `base`, so a local run also covers uncommitted edits.
|
|
73
|
+
*/
|
|
74
|
+
var checkChangelog = Effect.fnUntraced(function* ({ base: baseRef, cwd, event }) {
|
|
75
|
+
if (event && event !== "pull_request") {
|
|
76
|
+
yield* Console.log(`Skipping on \`${event}\` — the changelog check is diff-based.`);
|
|
77
|
+
return;
|
|
78
|
+
}
|
|
79
|
+
const fs = yield* FileSystem.FileSystem;
|
|
80
|
+
const path = yield* Path.Path;
|
|
81
|
+
const root = yield* git(cwd, "rev-parse", "--show-toplevel");
|
|
82
|
+
const base = yield* git(root, "merge-base", baseRef, "HEAD").pipe(Effect.orElseSucceed(() => baseRef));
|
|
83
|
+
const waivers = lines(yield* git(root, "log", `${base}..HEAD`, `--format=%(trailers:key=${WAIVER},valueonly)`));
|
|
84
|
+
if (waivers.length > 0) yield* Console.log(`Missing-decision rule waived by ${WAIVER}: ${waivers.join("; ")}`);
|
|
85
|
+
const changed = /* @__PURE__ */ new Map();
|
|
86
|
+
const quotePath = ["-c", "core.quotePath=false"];
|
|
87
|
+
for (const line of lines(yield* git(root, ...quotePath, "diff", "--name-status", "-M", "--diff-filter=AMR", base, "--", "*.mdl"))) {
|
|
88
|
+
const [status, ...paths] = line.split(" ");
|
|
89
|
+
changed.set(paths[paths.length - 1], status === "A" ? void 0 : paths[0]);
|
|
90
|
+
}
|
|
91
|
+
for (const file of lines(yield* git(root, ...quotePath, "ls-files", "--others", "--exclude-standard", "--", "*.mdl"))) changed.set(file, void 0);
|
|
92
|
+
let failures = 0;
|
|
93
|
+
for (const [file, basePath] of [...changed].sort(([a], [b]) => a.localeCompare(b))) {
|
|
94
|
+
if (EXEMPT.some((pattern) => pattern.test(file))) continue;
|
|
95
|
+
const after = yield* fs.readFileString(path.join(root, file));
|
|
96
|
+
const before = basePath === void 0 ? void 0 : yield* git(root, "show", `${base}:${basePath}`);
|
|
97
|
+
const errors = [...checkChangelogChange(before, after).filter((error) => waivers.length === 0 || error !== "The spec changed but no decision was added to `## Changelog`."), ...lintMdl(after).filter(({ source }) => source === "mdl/decision").map(({ message }) => message)];
|
|
98
|
+
for (const error of errors) yield* Console.log(`${file}: ${error}`);
|
|
99
|
+
failures += errors.length;
|
|
100
|
+
}
|
|
101
|
+
if (failures > 0) {
|
|
102
|
+
yield* Console.log(`\n${failures} changelog error(s). Every spec change adds a decision — see .agents/skills/mdl/SKILL.md.`);
|
|
103
|
+
return yield* Effect.fail(new ChangelogCheckError({ context: { failures } }));
|
|
104
|
+
}
|
|
105
|
+
yield* Console.log(`OK: ${changed.size} changed .mdl file(s) checked against ${baseRef}.`);
|
|
106
|
+
});
|
|
107
|
+
var check$2 = Command.make("check", { base: Flag.String("base").pipe(Flag.withDescription("Ref to diff against, via its merge base with HEAD (env MDL_BASE_REF)."), Flag.withFallbackConfig(Config.String("MDL_BASE_REF")), Flag.withDefault(DEFAULT_BASE_REF)) }, Effect.fnUntraced(function* ({ base }) {
|
|
108
|
+
const event = yield* Config.String("GITHUB_EVENT_NAME").pipe(Config.withDefault(""));
|
|
109
|
+
yield* checkChangelog({
|
|
110
|
+
base,
|
|
111
|
+
cwd: process.cwd(),
|
|
112
|
+
event
|
|
113
|
+
});
|
|
114
|
+
})).pipe(Command.withDescription("Fail when a changed .mdl spec adds no `## Changelog` decision or edits an existing one (waive with a `Spec-Changelog-Skip:` trailer)."));
|
|
115
|
+
var changelog = Command.make("changelog").pipe(Command.withDescription("Spec changelog tools."), Command.withSubcommands([check$2]));
|
|
116
|
+
//#endregion
|
|
117
|
+
//#region src/cli/review.ts
|
|
118
|
+
var STATUSES = /* @__PURE__ */ new Set([
|
|
119
|
+
"done",
|
|
120
|
+
"untested",
|
|
121
|
+
"partial",
|
|
122
|
+
"diverged",
|
|
123
|
+
"missing"
|
|
124
|
+
]);
|
|
125
|
+
/** Kinds a review judges. Acceptance blocks (scenarios, QA tests) are run, not reviewed; history is not code. */
|
|
126
|
+
var REVIEWED_KINDS = /* @__PURE__ */ new Set([
|
|
127
|
+
"plugin",
|
|
128
|
+
"feat",
|
|
129
|
+
"req",
|
|
130
|
+
"type",
|
|
131
|
+
"op",
|
|
132
|
+
"component",
|
|
133
|
+
"service",
|
|
134
|
+
"capability",
|
|
135
|
+
"module",
|
|
136
|
+
"db",
|
|
137
|
+
"scenario",
|
|
138
|
+
"test"
|
|
139
|
+
]);
|
|
140
|
+
/** A walkthrough says where things are; more steps than this retells the code. */
|
|
141
|
+
var MAX_WALKTHROUGH = 5;
|
|
142
|
+
/** Kinds judged on whether automation exercises them rather than on whether code implements them. */
|
|
143
|
+
var EXERCISE_KINDS = /* @__PURE__ */ new Set(["scenario", "test"]);
|
|
144
|
+
/** A key list written inline (`[a, b]`), wrapped over lines, or as `- a` items, as `parseReview` reads it. */
|
|
145
|
+
var keyList = (value) => (value ?? "").split(/[,\n]/).map((item) => item.replace(/^[\s[-]+|[\s\]]+$/g, "")).filter(Boolean);
|
|
146
|
+
var blocks = (text) => [...text.matchAll(/^```mdl\s*\n([\s\S]*?)^```/gm)].map((match) => ({
|
|
147
|
+
body: match[1],
|
|
148
|
+
line: text.slice(0, match.index).split("\n").length + 1
|
|
149
|
+
}));
|
|
150
|
+
/** Top-level blocks, plus `req` items nested in a `feat`; a feat with reqs is judged through them. */
|
|
151
|
+
var reviewItems = (text) => blocks(text).flatMap(({ body, line }) => {
|
|
152
|
+
const header = body.split("\n")[0].match(/^(\w+)\s+([A-Za-z][\w.-]*)\s*(?::\s*(.*))?$/);
|
|
153
|
+
if (!header || !REVIEWED_KINDS.has(header[1])) return [];
|
|
154
|
+
const nested = reqs(body).map(({ id, title, offset }) => ({
|
|
155
|
+
id,
|
|
156
|
+
kind: "req",
|
|
157
|
+
line: line + offset,
|
|
158
|
+
title
|
|
159
|
+
}));
|
|
160
|
+
return nested.length > 0 ? nested : [{
|
|
161
|
+
id: header[2],
|
|
162
|
+
kind: header[1],
|
|
163
|
+
line,
|
|
164
|
+
title: header[3] ?? ""
|
|
165
|
+
}];
|
|
166
|
+
});
|
|
167
|
+
/** A block field at two spaces of indent; a `|` value continues on lines indented four or more. */
|
|
168
|
+
var blockField = (body, name) => {
|
|
169
|
+
const match = body.match(new RegExp(`^ ${name}:[ \\t]*(.*)$((?:\\n {4,}.*)*)`, "m"));
|
|
170
|
+
return match ? `${match[1]} ${match[2]}`.replace(/^\|/, "").trim() : void 0;
|
|
171
|
+
};
|
|
172
|
+
/**
|
|
173
|
+
* The items a reference to `id` covers: a block's reqs (or the block itself when it has none), or one nested req.
|
|
174
|
+
*/
|
|
175
|
+
var itemsUnder = (text, id) => {
|
|
176
|
+
const block = blocks(text).find(({ body }) => body.split("\n")[0].match(/^\w+\s+([A-Za-z][\w.-]*)/)?.[1] === id);
|
|
177
|
+
if (block) {
|
|
178
|
+
const end = block.line + block.body.split("\n").length;
|
|
179
|
+
return reviewItems(text).filter(({ line }) => line >= block.line && line < end);
|
|
180
|
+
}
|
|
181
|
+
return reviewItems(text).filter((item) => item.id === id);
|
|
182
|
+
};
|
|
183
|
+
/** Each verdict's status and note, by item id. */
|
|
184
|
+
var reviewVerdicts = (text) => new Map(blocks(text).flatMap(({ body }) => {
|
|
185
|
+
const id = body.split("\n")[0].match(/^verdict\s+([A-Za-z][\w.-]*)/)?.[1];
|
|
186
|
+
return id ? [[id, {
|
|
187
|
+
status: blockField(body, "status"),
|
|
188
|
+
note: blockField(body, "note")
|
|
189
|
+
}]] : [];
|
|
190
|
+
}));
|
|
191
|
+
/**
|
|
192
|
+
* The `dependsOn` array of the `plugin` object in a `dx.config.ts`, empty when the object has none; undefined when
|
|
193
|
+
* there is no `plugin` object or `dependsOn` is not a literal array of strings. Comments are stripped first so a commented-out entry does not count.
|
|
194
|
+
*/
|
|
195
|
+
var configDependsOn = (configText) => {
|
|
196
|
+
const code = configText.replace(/(['"`])(?:\\.|(?!\1)[^\\])*\1|\/\/.*|\/\*[\s\S]*?\*\//g, (match) => match.startsWith("/") ? " " : match);
|
|
197
|
+
const start = /\bplugin\s*:\s*\{/.exec(code);
|
|
198
|
+
if (start?.index === void 0) return;
|
|
199
|
+
let depth = 0;
|
|
200
|
+
let end = code.length;
|
|
201
|
+
for (let index = start.index + start[0].length - 1; index < code.length; index++) {
|
|
202
|
+
depth += code[index] === "{" ? 1 : code[index] === "}" ? -1 : 0;
|
|
203
|
+
if (depth === 0) {
|
|
204
|
+
end = index;
|
|
205
|
+
break;
|
|
206
|
+
}
|
|
207
|
+
}
|
|
208
|
+
const plugin = code.slice(start.index, end);
|
|
209
|
+
if (!/\bdependsOn\s*:/.test(plugin)) return [];
|
|
210
|
+
const literal = plugin.match(/\bdependsOn\s*:\s*\[([^\]]*)\]/)?.[1];
|
|
211
|
+
if (literal === void 0) return;
|
|
212
|
+
const strings = literal.split(",").map((item) => item.trim()).filter((item) => item !== "").map((item) => item.match(/^(['"`])([^'"`$\\]*)\1$/)?.[2]);
|
|
213
|
+
return strings.every((value) => value !== void 0) ? strings.filter((value) => value !== void 0) : void 0;
|
|
214
|
+
};
|
|
215
|
+
/** Whether the source declares the name: a top-level declaration, a member, or an export list entry. */
|
|
216
|
+
var declares = (source, name) => {
|
|
217
|
+
const id = name.replace(/[$]/g, "\\$");
|
|
218
|
+
return [
|
|
219
|
+
new RegExp(`(?:class|interface|type|enum|function\\*?|const|let|var|namespace)\\s+${id}\\b`),
|
|
220
|
+
new RegExp(`^\\s*(?:(?:public|private|protected|static|readonly|override|async|get|set|#)\\s*)*${id}\\s*\\??[:(<=]`, "m"),
|
|
221
|
+
new RegExp(`export\\s*\\{[^}]*\\b${id}\\b`)
|
|
222
|
+
].some((pattern) => pattern.test(source));
|
|
223
|
+
};
|
|
224
|
+
/**
|
|
225
|
+
* Validates a `.review.mdl` against its spec and the checkout: frontmatter, statuses, notes, coverage of every item,
|
|
226
|
+
* and that each evidence key names an existing file and symbol.
|
|
227
|
+
*/
|
|
228
|
+
var checkReview = Effect.fnUntraced(function* (reviewPath) {
|
|
229
|
+
const fs = yield* FileSystem.FileSystem;
|
|
230
|
+
const path = yield* Path.Path;
|
|
231
|
+
const errors = [];
|
|
232
|
+
const warnings = [];
|
|
233
|
+
const text = yield* fs.readFileString(reviewPath);
|
|
234
|
+
const meta = frontmatter(text);
|
|
235
|
+
for (const key of [
|
|
236
|
+
"spec",
|
|
237
|
+
"commit",
|
|
238
|
+
"date",
|
|
239
|
+
"by"
|
|
240
|
+
]) if (!meta[key]) errors.push(`frontmatter: missing \`${key}\``);
|
|
241
|
+
if (meta.date && !/^\d{4}-\d{2}-\d{2}$/.test(meta.date)) errors.push("frontmatter: `date` must be YYYY-MM-DD");
|
|
242
|
+
if (meta.by && !/^(user|agent):\S+$/.test(meta.by)) errors.push("frontmatter: `by` must be `user:<handle>` or `agent:<name>`");
|
|
243
|
+
const root = yield* git(path.dirname(path.resolve(reviewPath)), "rev-parse", "--show-toplevel");
|
|
244
|
+
const realRoot = yield* fs.realPath(root);
|
|
245
|
+
const repo = Option.getOrUndefined(yield* git(root, "remote", "get-url", "origin").pipe(Effect.option, Effect.map(Option.flatMapNullishOr((url) => url.match(/github\.com[:/]([\w.-]+\/[\w.-]+?)(?:\.git)?\/?$/)?.[1]))));
|
|
246
|
+
if (meta.commit && Option.isNone(yield* git(root, "cat-file", "-e", `${meta.commit}^{commit}`).pipe(Effect.option))) warnings.push(`frontmatter: commit ${meta.commit} is not in this clone (shallow, or not fetched)`);
|
|
247
|
+
const exists = (file) => fs.exists(file).pipe(Effect.orElseSucceed(() => false));
|
|
248
|
+
const resolveKey = Effect.fnUntraced(function* (key) {
|
|
249
|
+
const match = key.match(/^github:([\w.-]+\/[\w.-]+)\/([^#\s]+)(?:#([\w$.-]+))?$/);
|
|
250
|
+
if (!match) return { error: `not a github: key: ${key}` };
|
|
251
|
+
if (repo && match[1].toLowerCase() !== repo.toLowerCase()) return {};
|
|
252
|
+
const file = path.resolve(root, match[2]);
|
|
253
|
+
const real = (yield* exists(file)) ? yield* fs.realPath(file) : file;
|
|
254
|
+
if (match[2].split("/").includes("..") || !real.startsWith(`${realRoot}${path.sep}`)) return { error: `key leaves the checkout: ${key}` };
|
|
255
|
+
return {
|
|
256
|
+
file,
|
|
257
|
+
symbol: match[3]
|
|
258
|
+
};
|
|
259
|
+
});
|
|
260
|
+
const specFile = meta.spec ? (yield* resolveKey(meta.spec)).file : void 0;
|
|
261
|
+
const specText = specFile && (yield* exists(specFile)) ? yield* fs.readFileString(specFile) : void 0;
|
|
262
|
+
if (meta.spec && !specText) errors.push(`frontmatter: spec not found in this checkout: ${meta.spec}`);
|
|
263
|
+
const items = specText ? reviewItems(specText) : [];
|
|
264
|
+
const itemIds = new Set(items.map(({ id }) => id));
|
|
265
|
+
const kindOf = new Map(items.map(({ id, kind }) => [id, kind]));
|
|
266
|
+
const verdicts = blocks(text).flatMap(({ body, line }) => {
|
|
267
|
+
const header = body.split("\n")[0].match(/^verdict\s+([A-Za-z][\w.-]*)\s*(?::\s*(.*))?$/);
|
|
268
|
+
return header ? [{
|
|
269
|
+
id: header[1],
|
|
270
|
+
line,
|
|
271
|
+
body
|
|
272
|
+
}] : [];
|
|
273
|
+
});
|
|
274
|
+
const seen = /* @__PURE__ */ new Set();
|
|
275
|
+
for (const { id, line, body } of verdicts) {
|
|
276
|
+
const at = `${reviewPath}:${line}`;
|
|
277
|
+
if (seen.has(id)) errors.push(`${at}: second verdict for ${id}`);
|
|
278
|
+
seen.add(id);
|
|
279
|
+
if (specText && !itemIds.has(id)) errors.push(`${at}: ${id} is not a reviewable item of the spec (run \`items\` for the list)`);
|
|
280
|
+
const status = blockField(body, "status");
|
|
281
|
+
if (!status || !STATUSES.has(status)) errors.push(`${at}: ${id} has status \`${status ?? ""}\`; use one of ${[...STATUSES].join(", ")}`);
|
|
282
|
+
if (status && status !== "done" && !blockField(body, "note")) errors.push(`${at}: ${id} is ${status} but has no note saying what is missing or different`);
|
|
283
|
+
const exercise = EXERCISE_KINDS.has(kindOf.get(id) ?? "");
|
|
284
|
+
const evidence = keyList(blockField(body, "evidence"));
|
|
285
|
+
if (!exercise && (status === "done" || status === "untested" || status === "partial") && evidence.length === 0) warnings.push(`${at}: ${id} is ${status} with no evidence`);
|
|
286
|
+
for (const key of evidence) {
|
|
287
|
+
const { file, symbol, error } = yield* resolveKey(key);
|
|
288
|
+
if (error) errors.push(`${at}: ${error}`);
|
|
289
|
+
else if (file && !(yield* exists(file))) errors.push(`${at}: evidence file not found: ${key}`);
|
|
290
|
+
else if (file && symbol) {
|
|
291
|
+
if (!declares(yield* fs.readFileString(file), symbol.split(".").pop() ?? symbol)) errors.push(`${at}: no declaration of ${symbol} in ${key.split("#")[0]} (a mention is not evidence)`);
|
|
292
|
+
}
|
|
293
|
+
}
|
|
294
|
+
const tests = keyList(blockField(body, "tests"));
|
|
295
|
+
if (exercise && status === "untested") errors.push(`${at}: ${id} is a ${kindOf.get(id)}; use done, partial, diverged or missing (see lang/review.mdl)`);
|
|
296
|
+
if (exercise && status !== "missing" && tests.length === 0) errors.push(`${at}: ${id} is a ${kindOf.get(id)} judged ${status} but cites no tests`);
|
|
297
|
+
if (status === "untested" && tests.length > 0) errors.push(`${at}: ${id} is untested but cites tests; make it done or drop the tests`);
|
|
298
|
+
if (!exercise && status === "done" && tests.length === 0) warnings.push(`${at}: ${id} is done with no tests; cite them or make it untested`);
|
|
299
|
+
for (const key of tests) {
|
|
300
|
+
const { file, symbol, error } = yield* resolveKey(key);
|
|
301
|
+
if (error) errors.push(`${at}: ${error}`);
|
|
302
|
+
else if (symbol) errors.push(`${at}: a test key names the test file only, without #: ${key}`);
|
|
303
|
+
else if (file && !(yield* exists(file))) errors.push(`${at}: test file not found: ${key}`);
|
|
304
|
+
}
|
|
305
|
+
const steps = (blockField(body, "walkthrough") ?? "").split(/(?:^|\s)-\s+/).map((step) => step.trim()).filter(Boolean);
|
|
306
|
+
if (steps.length > MAX_WALKTHROUGH) errors.push(`${at}: ${id} has ${steps.length} walkthrough steps; keep it to ${MAX_WALKTHROUGH}`);
|
|
307
|
+
if (steps.length > 0 && evidence.length < 2) warnings.push(`${at}: ${id} has one implementation; its code chip already shows it, so drop the walkthrough`);
|
|
308
|
+
for (const step of steps) {
|
|
309
|
+
const key = step.match(/(github:\S+)\s*$/)?.[1];
|
|
310
|
+
if (!key) {
|
|
311
|
+
errors.push(`${at}: walkthrough step does not end with a github: key: ${step}`);
|
|
312
|
+
continue;
|
|
313
|
+
}
|
|
314
|
+
const { file, symbol, error } = yield* resolveKey(key);
|
|
315
|
+
if (error) errors.push(`${at}: ${error}`);
|
|
316
|
+
else if (file && !(yield* exists(file))) errors.push(`${at}: walkthrough file not found: ${key}`);
|
|
317
|
+
else if (file && symbol) {
|
|
318
|
+
if (!declares(yield* fs.readFileString(file), symbol.split(".").pop() ?? symbol)) errors.push(`${at}: no declaration of ${symbol} in ${key.split("#")[0]} (walkthrough)`);
|
|
319
|
+
}
|
|
320
|
+
}
|
|
321
|
+
}
|
|
322
|
+
const pluginBlock = specText ? parseMdlBlocks(specText).find(({ type }) => type === "plugin") : void 0;
|
|
323
|
+
const configFile = specFile ? path.join(path.dirname(specFile), "dx.config.ts") : void 0;
|
|
324
|
+
if (specText && pluginBlock && configFile && (yield* exists(configFile))) {
|
|
325
|
+
const config = configDependsOn(yield* fs.readFileString(configFile));
|
|
326
|
+
const declared = specDependencies(specText).filter(({ via }) => via === "dependsOn").map(({ id }) => id);
|
|
327
|
+
const verdict = verdicts.find(({ id }) => id === pluginBlock.id);
|
|
328
|
+
if (config && verdict && blockField(verdict.body, "status") !== "diverged") {
|
|
329
|
+
if (!(new Set(declared).size === new Set(config).size && declared.every((id) => config.includes(id)))) errors.push(`${reviewPath}:${verdict.line}: ${pluginBlock.id} dependsOn [${declared.join(", ")}] differs from dx.config.ts [${config.join(", ")}]; judge it diverged`);
|
|
330
|
+
}
|
|
331
|
+
}
|
|
332
|
+
for (const { id, line } of items) if (!seen.has(id)) errors.push(`${specFile}:${line}: ${id} has no verdict`);
|
|
333
|
+
for (const warning of warnings) yield* Console.log(`warning: ${warning}`);
|
|
334
|
+
for (const error of errors) yield* Console.log(`error: ${error}`);
|
|
335
|
+
yield* Console.log(`${verdicts.length} verdicts for ${items.length} items; ${errors.length} errors, ${warnings.length} warnings.`);
|
|
336
|
+
if (errors.length > 0) return yield* Effect.fail(new ReviewCheckError({ context: { errors: errors.length } }));
|
|
337
|
+
});
|
|
338
|
+
var items = Command.make("items", { spec: Argument.String("spec").pipe(Argument.withDescription("The spec (.mdl) to list.")) }, Effect.fnUntraced(function* ({ spec }) {
|
|
339
|
+
const fs = yield* FileSystem.FileSystem;
|
|
340
|
+
for (const { id, kind, line, title } of reviewItems(yield* fs.readFileString(spec))) yield* Console.log(`${id}\t${kind}\t${line}\t${title}`);
|
|
341
|
+
})).pipe(Command.withDescription("List every item a spec review must judge: `<id>\\t<kind>\\t<line>\\t<title>`."));
|
|
342
|
+
var check$1 = Command.make("check", { review: Argument.String("review").pipe(Argument.withDescription("The review (.review.mdl) to validate.")) }, ({ review }) => checkReview(review)).pipe(Command.withDescription("Validate a spec review against its spec and the checkout."));
|
|
343
|
+
var review = Command.make("review").pipe(Command.withDescription("Spec review tools."), Command.withSubcommands([items, check$1]));
|
|
344
|
+
//#endregion
|
|
345
|
+
//#region src/cli/features.ts
|
|
346
|
+
/** The authored statuses of `lang/features.mdl`, in the order a feature normally moves through them. */
|
|
347
|
+
var FEATURE_STATUSES = [
|
|
348
|
+
"planned",
|
|
349
|
+
"in-progress",
|
|
350
|
+
"prototype",
|
|
351
|
+
"operational",
|
|
352
|
+
"failing"
|
|
353
|
+
];
|
|
354
|
+
/** Every `feature` block of a feature map. */
|
|
355
|
+
var parseFeatureMap = (text) => parseMdlBlocks(text).filter(({ type }) => type === "feature").map(({ id, title, body, from }) => ({
|
|
356
|
+
id: id ?? "",
|
|
357
|
+
title: title ?? "",
|
|
358
|
+
line: text.slice(0, from).split("\n").length,
|
|
359
|
+
status: blockField(body, "status"),
|
|
360
|
+
specs: keyList(blockField(body, "specs")),
|
|
361
|
+
depends: keyList(blockField(body, "depends"))
|
|
362
|
+
}));
|
|
363
|
+
/**
|
|
364
|
+
* The status the reviews support: every item done is operational, done or untested is a prototype, every item
|
|
365
|
+
* missing is planned, and anything between is in progress.
|
|
366
|
+
*/
|
|
367
|
+
var deriveStatus = (statuses) => {
|
|
368
|
+
if (statuses.length === 0 || statuses.some((status) => status === void 0)) return "unreviewed";
|
|
369
|
+
if (statuses.every((status) => status === "done")) return "operational";
|
|
370
|
+
if (statuses.every((status) => status === "done" || status === "untested")) return "prototype";
|
|
371
|
+
if (statuses.every((status) => status === "missing")) return "planned";
|
|
372
|
+
return "in-progress";
|
|
373
|
+
};
|
|
374
|
+
var REVIEW_SUFFIX = ".review.mdl";
|
|
375
|
+
/** Finds the first dependency cycle as the ids along it, closing on the id it started from. */
|
|
376
|
+
var findCycle = (features) => {
|
|
377
|
+
const depends = new Map(features.map(({ id, depends }) => [id, depends]));
|
|
378
|
+
const done = /* @__PURE__ */ new Set();
|
|
379
|
+
const visit = (id, trail) => {
|
|
380
|
+
if (trail.includes(id)) return [...trail.slice(trail.indexOf(id)), id];
|
|
381
|
+
if (done.has(id)) return;
|
|
382
|
+
for (const next of depends.get(id) ?? []) {
|
|
383
|
+
const cycle = visit(next, [...trail, id]);
|
|
384
|
+
if (cycle) return cycle;
|
|
385
|
+
}
|
|
386
|
+
done.add(id);
|
|
387
|
+
};
|
|
388
|
+
for (const { id } of features) {
|
|
389
|
+
const cycle = visit(id, []);
|
|
390
|
+
if (cycle) return cycle;
|
|
391
|
+
}
|
|
392
|
+
};
|
|
393
|
+
/**
|
|
394
|
+
* Resolves every spec reference of a feature map against the checkout and its reviews, derives each feature's status,
|
|
395
|
+
* and collects what is wrong (errors) or out of step (warnings).
|
|
396
|
+
*/
|
|
397
|
+
var analyzeFeatureMap = Effect.fnUntraced(function* (mapPath) {
|
|
398
|
+
const fs = yield* FileSystem.FileSystem;
|
|
399
|
+
const path = yield* Path.Path;
|
|
400
|
+
const root = yield* git(path.dirname(path.resolve(mapPath)), "rev-parse", "--show-toplevel");
|
|
401
|
+
const features = parseFeatureMap(yield* fs.readFileString(mapPath));
|
|
402
|
+
const errors = [];
|
|
403
|
+
const warnings = [];
|
|
404
|
+
const exists = (file) => fs.exists(file).pipe(Effect.orElseSucceed(() => false));
|
|
405
|
+
const readIfExists = Effect.fnUntraced(function* (file) {
|
|
406
|
+
return (yield* exists(file)) ? yield* fs.readFileString(file) : void 0;
|
|
407
|
+
});
|
|
408
|
+
const byId = /* @__PURE__ */ new Map();
|
|
409
|
+
for (const feature of features) {
|
|
410
|
+
const at = `${mapPath}:${feature.line}: ${feature.id}`;
|
|
411
|
+
if (byId.has(feature.id)) errors.push(`${at}: second feature with this id`);
|
|
412
|
+
byId.set(feature.id, feature);
|
|
413
|
+
if (!feature.status || !FEATURE_STATUSES.includes(feature.status)) errors.push(`${at}: status \`${feature.status ?? ""}\`; use one of ${FEATURE_STATUSES.join(", ")}`);
|
|
414
|
+
if (feature.specs.length === 0) errors.push(`${at}: cites no spec; a feature names the spec items that state it`);
|
|
415
|
+
}
|
|
416
|
+
for (const feature of features) for (const dependency of feature.depends) if (!byId.has(dependency)) errors.push(`${mapPath}:${feature.line}: ${feature.id}: depends on unknown feature ${dependency}`);
|
|
417
|
+
const cycle = findCycle(features);
|
|
418
|
+
if (cycle) errors.push(`${mapPath}: dependency cycle: ${cycle.join(" -> ")}`);
|
|
419
|
+
const specs = /* @__PURE__ */ new Map();
|
|
420
|
+
const loadSpec = Effect.fnUntraced(function* (spec, at) {
|
|
421
|
+
const cached = specs.get(spec);
|
|
422
|
+
if (cached) return cached;
|
|
423
|
+
const file = path.resolve(root, spec);
|
|
424
|
+
const text = yield* readIfExists(file);
|
|
425
|
+
const reviewFile = file.replace(/\.mdl$/, REVIEW_SUFFIX);
|
|
426
|
+
const review = text ? yield* readIfExists(reviewFile) : void 0;
|
|
427
|
+
if (!text) errors.push(`${at}: spec not found: ${spec}`);
|
|
428
|
+
else if (!review) warnings.push(`${at}: ${spec} has no review; run the spec-review skill`);
|
|
429
|
+
else {
|
|
430
|
+
const commit = frontmatter(review).commit;
|
|
431
|
+
const changed = commit ? yield* git(root, "rev-list", `${commit}..HEAD`, "--", spec).pipe(Effect.option) : Option.none();
|
|
432
|
+
const dirty = yield* git(root, "status", "--porcelain", "--", spec).pipe(Effect.orElseSucceed(() => ""));
|
|
433
|
+
if (Option.isNone(changed)) warnings.push(`${at}: the review of ${spec} names a commit not in this clone`);
|
|
434
|
+
else if (changed.value !== "" || dirty !== "") warnings.push(`${at}: ${spec} changed after its review (${commit?.slice(0, 8)}); re-review it`);
|
|
435
|
+
}
|
|
436
|
+
const entry = {
|
|
437
|
+
text,
|
|
438
|
+
verdicts: review ? reviewVerdicts(review) : /* @__PURE__ */ new Map()
|
|
439
|
+
};
|
|
440
|
+
specs.set(spec, entry);
|
|
441
|
+
return entry;
|
|
442
|
+
});
|
|
443
|
+
const reports = [];
|
|
444
|
+
for (const feature of features) {
|
|
445
|
+
const at = `${mapPath}:${feature.line}: ${feature.id}`;
|
|
446
|
+
const items = [];
|
|
447
|
+
for (const ref of feature.specs) {
|
|
448
|
+
const [spec, id] = ref.split("#");
|
|
449
|
+
const { text, verdicts } = yield* loadSpec(spec, at);
|
|
450
|
+
if (!text) continue;
|
|
451
|
+
const cited = id ? itemsUnder(text, id) : reviewItems(text);
|
|
452
|
+
if (cited.length === 0) errors.push(`${at}: ${ref} names no reviewable item of the spec`);
|
|
453
|
+
items.push(...cited.map((item) => ({
|
|
454
|
+
...item,
|
|
455
|
+
spec,
|
|
456
|
+
...verdicts.get(item.id)
|
|
457
|
+
})));
|
|
458
|
+
}
|
|
459
|
+
const derived = deriveStatus(items.map(({ status }) => status));
|
|
460
|
+
const unjudged = items.filter(({ status }) => status === void 0).map(({ id }) => id);
|
|
461
|
+
if (unjudged.length > 0 && unjudged.length < items.length) warnings.push(`${at}: no verdict yet for ${unjudged.join(", ")}`);
|
|
462
|
+
if (feature.status && feature.status !== "failing" && derived !== "unreviewed" && feature.status !== derived) warnings.push(`${at}: marked ${feature.status} but its reviews say ${derived}`);
|
|
463
|
+
for (const dependency of feature.depends) {
|
|
464
|
+
const status = byId.get(dependency)?.status;
|
|
465
|
+
if (feature.status !== "planned" && (status === "planned" || status === "failing")) warnings.push(`${at}: blocked: depends on ${dependency}, which is ${status}`);
|
|
466
|
+
else if (feature.status === "operational" && status !== "operational") warnings.push(`${at}: operational ahead of its dependency ${dependency} (${status})`);
|
|
467
|
+
}
|
|
468
|
+
if (feature.status === "in-progress") {
|
|
469
|
+
const dirs = new Set(items.flatMap(({ spec }) => {
|
|
470
|
+
const dir = path.dirname(path.resolve(root, spec));
|
|
471
|
+
return ["spec", "docs"].includes(path.basename(dir)) ? [dir, path.dirname(dir)] : [dir];
|
|
472
|
+
}));
|
|
473
|
+
let planned = false;
|
|
474
|
+
for (const dir of dirs) {
|
|
475
|
+
const tasks = yield* readIfExists(path.join(dir, "TASKS.md"));
|
|
476
|
+
planned ||= tasks !== void 0 && new RegExp(`^#{2,3} .*\\b${feature.id.replace(/\./g, "\\.")}\\b`, "m").test(tasks);
|
|
477
|
+
}
|
|
478
|
+
if (!planned) warnings.push(`${at}: partly built with no work planned: no TASKS.md beside its spec has a \`## ${feature.id}\` section`);
|
|
479
|
+
}
|
|
480
|
+
reports.push({
|
|
481
|
+
feature,
|
|
482
|
+
derived,
|
|
483
|
+
items
|
|
484
|
+
});
|
|
485
|
+
}
|
|
486
|
+
return {
|
|
487
|
+
reports,
|
|
488
|
+
errors,
|
|
489
|
+
warnings
|
|
490
|
+
};
|
|
491
|
+
});
|
|
492
|
+
var DEFAULT_MAP = "FEATURES.mdl";
|
|
493
|
+
var resolveMap = Effect.fnUntraced(function* (map) {
|
|
494
|
+
if (Option.isSome(map)) return map.value;
|
|
495
|
+
return (yield* Path.Path).join(yield* git(process.cwd(), "rev-parse", "--show-toplevel"), DEFAULT_MAP);
|
|
496
|
+
});
|
|
497
|
+
var mapFlag = Flag.String("map").pipe(Flag.withDescription(`The feature map; defaults to ${DEFAULT_MAP} at the repository root.`), Flag.optional);
|
|
498
|
+
/** Prints one row per feature, then every warning and error; fails when there is an error. */
|
|
499
|
+
var checkFeatures = Effect.fnUntraced(function* (mapPath) {
|
|
500
|
+
const { reports, errors, warnings } = yield* analyzeFeatureMap(mapPath);
|
|
501
|
+
for (const { feature, derived, items } of reports) {
|
|
502
|
+
const done = items.filter(({ status }) => status === "done").length;
|
|
503
|
+
yield* Console.log(`${feature.id}\t${feature.status ?? ""}\t${derived}\t${done}/${items.length} done`);
|
|
504
|
+
}
|
|
505
|
+
for (const warning of warnings) yield* Console.log(`warning: ${warning}`);
|
|
506
|
+
for (const error of errors) yield* Console.log(`error: ${error}`);
|
|
507
|
+
yield* Console.log(`${reports.length} features; ${errors.length} errors, ${warnings.length} warnings.`);
|
|
508
|
+
if (errors.length > 0) return yield* Effect.fail(new FeatureCheckError({ context: { errors: errors.length } }));
|
|
509
|
+
});
|
|
510
|
+
/** The first sentence of a verdict note, so a task line stays one line. */
|
|
511
|
+
var firstSentence = (note) => (note ?? "").replace(/\s+/g, " ").match(/^.*?[.!?](?=\s|$)/)?.[0] ?? (note ?? "").trim();
|
|
512
|
+
/** Prints the open work of one feature as a TASKS.md section: one task per spec item not yet done. */
|
|
513
|
+
var featureTasks = Effect.fnUntraced(function* (mapPath, id) {
|
|
514
|
+
const { reports } = yield* analyzeFeatureMap(mapPath);
|
|
515
|
+
const report = reports.find(({ feature }) => feature.id === id);
|
|
516
|
+
if (!report) return yield* Effect.fail(new FeatureCheckError({ context: {
|
|
517
|
+
feature: id,
|
|
518
|
+
reason: "not on the map"
|
|
519
|
+
} }));
|
|
520
|
+
yield* Console.log(`## ${report.feature.id}: ${report.feature.title}\n`);
|
|
521
|
+
let spec;
|
|
522
|
+
for (const item of report.items.filter(({ status }) => status !== "done")) {
|
|
523
|
+
if (item.spec !== spec) {
|
|
524
|
+
spec = item.spec;
|
|
525
|
+
yield* Console.log(`Spec: \`${spec}\`\n`);
|
|
526
|
+
}
|
|
527
|
+
const why = item.status ? `${item.status}${item.note ? `: ${firstSentence(item.note)}` : ""}` : "unreviewed";
|
|
528
|
+
yield* Console.log(`- [ ] ${item.id}: ${item.title} (${why})`);
|
|
529
|
+
}
|
|
530
|
+
});
|
|
531
|
+
var check = Command.make("check", { map: mapFlag }, ({ map }) => Effect.flatMap(resolveMap(map), checkFeatures)).pipe(Command.withDescription("Check the feature map against the specs and their reviews: `<id>\\t<status>\\t<derived>\\t<done>/<items> done`."));
|
|
532
|
+
var tasks = Command.make("tasks", {
|
|
533
|
+
map: mapFlag,
|
|
534
|
+
feature: Argument.String("feature").pipe(Argument.withDescription("The feature id."))
|
|
535
|
+
}, ({ map, feature }) => Effect.flatMap(resolveMap(map), (mapPath) => featureTasks(mapPath, feature))).pipe(Command.withDescription("Print the open spec items of one feature as a TASKS.md section."));
|
|
536
|
+
var features = Command.make("features").pipe(Command.withDescription("Feature map tools: the top of feature map > specs > tasks > code > result."), Command.withSubcommands([check, tasks]));
|
|
537
|
+
//#endregion
|
|
538
|
+
//#region src/cli/spec-index.ts
|
|
539
|
+
/** Indexes every tracked `.mdl` spec under `root`, leaving out what {@link isIndexedSpec} excludes. */
|
|
540
|
+
var buildSpecIndex = Effect.fnUntraced(function* (root) {
|
|
541
|
+
const fs = yield* FileSystem.FileSystem;
|
|
542
|
+
const path = yield* Path.Path;
|
|
543
|
+
const tracked = lines(yield* git(root, "-c", "core.quotePath=false", "ls-files", "--", "*.mdl")).filter(isIndexedSpec);
|
|
544
|
+
const files = yield* Effect.forEach(tracked, (file) => fs.readFileString(path.join(root, file)).pipe(Effect.map((text) => ({
|
|
545
|
+
path: file,
|
|
546
|
+
text
|
|
547
|
+
})), Effect.option));
|
|
548
|
+
return indexSpecs(files.flatMap((file) => file._tag === "Some" ? [file.value] : []));
|
|
549
|
+
});
|
|
550
|
+
/** Indexes every spec of the checkout by id and prints the JSON, or writes it to `out`. */
|
|
551
|
+
var printIndex = Effect.fnUntraced(function* ({ out }) {
|
|
552
|
+
const fs = yield* FileSystem.FileSystem;
|
|
553
|
+
const root = yield* git(process.cwd(), "rev-parse", "--show-toplevel");
|
|
554
|
+
const json = JSON.stringify(yield* buildSpecIndex(root), null, 2);
|
|
555
|
+
if (Option.isSome(out)) yield* fs.writeFileString(out.value, `${json}\n`);
|
|
556
|
+
else yield* Console.log(json);
|
|
557
|
+
});
|
|
558
|
+
var index = Command.make("index", { out: Flag.String("out").pipe(Flag.withDescription("Write the index to this file."), Flag.optional) }, printIndex).pipe(Command.withDescription("Index every .mdl spec of the checkout by its frontmatter id."));
|
|
559
|
+
//#endregion
|
|
560
|
+
//#region src/cli/lint.ts
|
|
561
|
+
var INDEXED_CHECKS = ["mdl/ref", "mdl/uses"];
|
|
562
|
+
/** Lints .mdl files with the checks the editor runs; fails when any diagnostic is an error. */
|
|
563
|
+
var lintFiles = Effect.fnUntraced(function* ({ files, only }) {
|
|
564
|
+
const fs = yield* FileSystem.FileSystem;
|
|
565
|
+
const needsIndex = Option.isNone(only) || INDEXED_CHECKS.includes(only.value);
|
|
566
|
+
const root = needsIndex ? yield* git(process.cwd(), "rev-parse", "--show-toplevel").pipe(Effect.catch((error) => String(error.context?.stderr).includes("not a git repository") ? Effect.succeed(void 0) : Effect.fail(error))) : void 0;
|
|
567
|
+
if (needsIndex && root === void 0) yield* Console.log("warning: not inside a git checkout; the mdl/ref and mdl/uses checks were skipped.");
|
|
568
|
+
const index = root === void 0 ? void 0 : yield* buildSpecIndex(root);
|
|
569
|
+
let errors = 0;
|
|
570
|
+
for (const file of files) {
|
|
571
|
+
const text = yield* fs.readFileString(file);
|
|
572
|
+
for (const { from, severity, source, message } of lintMdl(text, { index: file.endsWith(".review.mdl") ? void 0 : index })) {
|
|
573
|
+
if (Option.isSome(only) && source !== only.value) continue;
|
|
574
|
+
const line = text.slice(0, from).split("\n").length;
|
|
575
|
+
yield* Console.log(`${file}:${line}: ${severity} [${source}]: ${message}`);
|
|
576
|
+
if (severity === "error") errors++;
|
|
577
|
+
}
|
|
578
|
+
}
|
|
579
|
+
if (errors > 0) return yield* Effect.fail(new LintError({ context: { errors } }));
|
|
580
|
+
});
|
|
581
|
+
var lint = Command.make("lint", {
|
|
582
|
+
only: Flag.String("only").pipe(Flag.withDescription("Report one check only, e.g. `mdl/decision`."), Flag.optional),
|
|
583
|
+
files: Argument.String("files").pipe(Argument.withDescription("The .mdl files to lint."), Argument.variadic({ min: 1 }))
|
|
584
|
+
}, lintFiles).pipe(Command.withDescription("Lint .mdl files with the checks the editor runs."));
|
|
585
|
+
//#endregion
|
|
586
|
+
//#region src/cli/qa-lint.ts
|
|
587
|
+
/** Names the runner binds itself (qa.mdl Field rule 5 and Input literals), so no test declares them. */
|
|
588
|
+
var RUNNER_BOUND = /* @__PURE__ */ new Set([
|
|
589
|
+
"given",
|
|
590
|
+
"result",
|
|
591
|
+
"error",
|
|
592
|
+
"spaceId",
|
|
593
|
+
"snapshot",
|
|
594
|
+
"stepErrors",
|
|
595
|
+
"runId"
|
|
596
|
+
]);
|
|
597
|
+
/** `test QA-n` blocks whose steps reference a `$given.x` or `$x` the test never binds. */
|
|
598
|
+
var findUnboundReferences = (file, text) => {
|
|
599
|
+
const lines = text.split("\n");
|
|
600
|
+
const tests = [];
|
|
601
|
+
let current;
|
|
602
|
+
lines.forEach((line, index) => {
|
|
603
|
+
const header = line.match(/^test (QA-\d+):/);
|
|
604
|
+
if (header) {
|
|
605
|
+
current = {
|
|
606
|
+
name: header[1],
|
|
607
|
+
body: []
|
|
608
|
+
};
|
|
609
|
+
tests.push(current);
|
|
610
|
+
} else if (current && line.startsWith("```")) current = void 0;
|
|
611
|
+
else if (current) current.body.push({
|
|
612
|
+
line: index + 1,
|
|
613
|
+
text: line
|
|
614
|
+
});
|
|
615
|
+
});
|
|
616
|
+
return tests.flatMap((test) => {
|
|
617
|
+
const text = test.body.map(({ text }) => text).join("\n");
|
|
618
|
+
const givens = /* @__PURE__ */ new Set();
|
|
619
|
+
let inGiven = false;
|
|
620
|
+
for (const { text: line } of test.body) {
|
|
621
|
+
if (/^\s{2}given:/.test(line)) {
|
|
622
|
+
inGiven = true;
|
|
623
|
+
continue;
|
|
624
|
+
}
|
|
625
|
+
if (/^\s{2}\w+[?]?:/.test(line)) inGiven = false;
|
|
626
|
+
const entry = inGiven ? line.match(/^\s*-\s+([A-Za-z_][A-Za-z0-9_]*):\s/) : null;
|
|
627
|
+
if (entry) givens.add(entry[1]);
|
|
628
|
+
}
|
|
629
|
+
const captures = new Set([...text.matchAll(/^\s*capture:\s*([A-Za-z_][A-Za-z0-9_]*)/gm)].map((match) => match[1]));
|
|
630
|
+
const unbound = /* @__PURE__ */ new Map();
|
|
631
|
+
for (const { line, text: content } of test.body) {
|
|
632
|
+
for (const match of content.matchAll(/\$given\.([A-Za-z_][A-Za-z0-9_]*)/g)) if (!givens.has(match[1])) unbound.set(`$given.${match[1]}`, line);
|
|
633
|
+
for (const match of content.matchAll(/\$([A-Za-z_][A-Za-z0-9_]*)/g)) if (!RUNNER_BOUND.has(match[1]) && !captures.has(match[1])) unbound.set(`$${match[1]}`, line);
|
|
634
|
+
}
|
|
635
|
+
return unbound.size > 0 ? [{
|
|
636
|
+
file,
|
|
637
|
+
test: test.name,
|
|
638
|
+
unbound: [...unbound.entries()]
|
|
639
|
+
}] : [];
|
|
640
|
+
});
|
|
641
|
+
};
|
|
642
|
+
/**
|
|
643
|
+
* `after:` steps that could remove an object the run did not create.
|
|
644
|
+
*
|
|
645
|
+
* A teardown is safe when it removes something the test bound itself (a `capture:` or a named `given:`), or resolves
|
|
646
|
+
* by a name the test's `given` guarantees is absent — constrained to the subject's own type, and throwing when nothing
|
|
647
|
+
* matches. Resolving by type-and-index deletes whatever the space happens to hold first; resolving by name across
|
|
648
|
+
* `Filter.everything()` deletes any object carrying that name, which the `given` precondition does not exclude.
|
|
649
|
+
*/
|
|
650
|
+
var findUnsafeTeardowns = (file, text) => {
|
|
651
|
+
const lines = text.split("\n");
|
|
652
|
+
const reports = [];
|
|
653
|
+
let inAfter = false;
|
|
654
|
+
let test = "";
|
|
655
|
+
lines.forEach((line, index) => {
|
|
656
|
+
const header = line.match(/^test (QA-\d+):/);
|
|
657
|
+
if (header) {
|
|
658
|
+
test = header[1];
|
|
659
|
+
inAfter = false;
|
|
660
|
+
}
|
|
661
|
+
if (/^ {2}after:/.test(line)) {
|
|
662
|
+
inAfter = true;
|
|
663
|
+
return;
|
|
664
|
+
}
|
|
665
|
+
if (/^ {2}(steps|before|given):/.test(line) || line.startsWith("```")) inAfter = false;
|
|
666
|
+
if (!inAfter || !/removeObjects/.test(line)) return;
|
|
667
|
+
const step = [];
|
|
668
|
+
for (let next = index; next < lines.length; next++) {
|
|
669
|
+
if (next > index && /^\s+(assert|expect|note|do|name|capture):/.test(lines[next])) break;
|
|
670
|
+
step.push(lines[next]);
|
|
671
|
+
}
|
|
672
|
+
const body = step.join("\n");
|
|
673
|
+
if (!/db\.query/.test(body)) return;
|
|
674
|
+
const byIndex = /\.objects\[\d+\]/.test(body);
|
|
675
|
+
const guarded = /throw new Error/.test(body);
|
|
676
|
+
const untyped = /Filter\.everything\(\)/.test(body) && /\.name ===/.test(body);
|
|
677
|
+
const byIdentity = /\.id ===/.test(body);
|
|
678
|
+
if (byIndex || untyped || !guarded && !byIdentity) {
|
|
679
|
+
const reason = byIndex ? "resolves by index" : untyped ? "name match across every type" : "unguarded query";
|
|
680
|
+
reports.push({
|
|
681
|
+
file,
|
|
682
|
+
test,
|
|
683
|
+
line: index + 1,
|
|
684
|
+
reason
|
|
685
|
+
});
|
|
686
|
+
}
|
|
687
|
+
});
|
|
688
|
+
return reports;
|
|
689
|
+
};
|
|
690
|
+
/** The plugin specs the QA lints cover: `packages/plugins/<plugin>/PLUGIN.mdl`, sorted, relative to `root`. */
|
|
691
|
+
var pluginSpecs = Effect.fnUntraced(function* (root) {
|
|
692
|
+
const fs = yield* FileSystem.FileSystem;
|
|
693
|
+
const path = yield* Path.Path;
|
|
694
|
+
const plugins = (yield* fs.readDirectory(path.join(root, "packages/plugins"))).sort();
|
|
695
|
+
const specs = [];
|
|
696
|
+
for (const plugin of plugins) {
|
|
697
|
+
const file = `packages/plugins/${plugin}/PLUGIN.mdl`;
|
|
698
|
+
const text = yield* fs.readFileString(path.join(root, file)).pipe(Effect.option);
|
|
699
|
+
if (Option.isSome(text)) specs.push({
|
|
700
|
+
file,
|
|
701
|
+
text: text.value
|
|
702
|
+
});
|
|
703
|
+
}
|
|
704
|
+
return specs;
|
|
705
|
+
});
|
|
706
|
+
var QA_CHECKS = ["unbound", "teardown"];
|
|
707
|
+
/** Runs the QA lints over every plugin spec under `root`; fails when any reports a finding. */
|
|
708
|
+
var lintQa = Effect.fnUntraced(function* ({ root, checks }) {
|
|
709
|
+
const specs = yield* pluginSpecs(root);
|
|
710
|
+
let findings = 0;
|
|
711
|
+
if (checks.includes("unbound")) {
|
|
712
|
+
const reports = specs.flatMap(({ file, text }) => findUnboundReferences(file, text));
|
|
713
|
+
let total = 0;
|
|
714
|
+
for (const report of reports) {
|
|
715
|
+
yield* Console.log(`${report.file} ${report.test}`);
|
|
716
|
+
for (const [name, line] of report.unbound) {
|
|
717
|
+
yield* Console.log(` L${line} ${name}`);
|
|
718
|
+
total++;
|
|
719
|
+
}
|
|
720
|
+
}
|
|
721
|
+
yield* Console.log(`\n${reports.length} tests with unbound references; ${total} references total`);
|
|
722
|
+
findings += total;
|
|
723
|
+
}
|
|
724
|
+
if (checks.includes("teardown")) {
|
|
725
|
+
const reports = specs.flatMap(({ file, text }) => findUnsafeTeardowns(file, text));
|
|
726
|
+
for (const { file, test, line, reason } of reports) yield* Console.log(`${file} ${test} L${line} ${reason}`);
|
|
727
|
+
yield* Console.log(`\n${reports.length} teardown step(s) that could remove an object the run did not create`);
|
|
728
|
+
findings += reports.length;
|
|
729
|
+
}
|
|
730
|
+
if (findings > 0) return yield* Effect.fail(new QaLintError({ context: { findings } }));
|
|
731
|
+
});
|
|
732
|
+
var qaLint = Command.make("lint", {
|
|
733
|
+
check: Flag.Literals("check", QA_CHECKS).pipe(Flag.withDescription("Run one check: `unbound` ($references a test never binds) or `teardown` (unsafe `after:` removals)."), Flag.optional),
|
|
734
|
+
root: Flag.String("root").pipe(Flag.withDescription("Repository root holding `packages/plugins` (default the working directory)."), Flag.withDefault(process.cwd()))
|
|
735
|
+
}, ({ check, root }) => lintQa({
|
|
736
|
+
root,
|
|
737
|
+
checks: Option.match(check, {
|
|
738
|
+
onNone: () => QA_CHECKS,
|
|
739
|
+
onSome: (one) => [one]
|
|
740
|
+
})
|
|
741
|
+
})).pipe(Command.withDescription("Lint the `test` blocks of every plugin spec for unbound references and unsafe teardowns."));
|
|
742
|
+
//#endregion
|
|
743
|
+
//#region src/cli/qa.ts
|
|
744
|
+
/**
|
|
745
|
+
* Whether a host CLI asked for JSON output. `dx` declares `--json` as a shared root flag, which consumes it before
|
|
746
|
+
* `dx deus qa list` sees its own, so `dx` provides this instead.
|
|
747
|
+
*/
|
|
748
|
+
var JsonOutput = Context.Reference("@dxos/deus/JsonOutput", { defaultValue: () => false });
|
|
749
|
+
/** Directories never searched; `__fixtures__` hold test inputs, not runnable plans. */
|
|
750
|
+
var SKIP = /* @__PURE__ */ new Set([
|
|
751
|
+
"node_modules",
|
|
752
|
+
"dist",
|
|
753
|
+
".git",
|
|
754
|
+
".moon",
|
|
755
|
+
"out",
|
|
756
|
+
"temp",
|
|
757
|
+
".cache",
|
|
758
|
+
"__fixtures__"
|
|
759
|
+
]);
|
|
760
|
+
var STAGES = [
|
|
761
|
+
"before",
|
|
762
|
+
"steps",
|
|
763
|
+
"after"
|
|
764
|
+
];
|
|
765
|
+
/** Steps per stage. A stage header sits at two spaces; its steps are `- name:`/`- do:` at four. */
|
|
766
|
+
var countStages = (body) => {
|
|
767
|
+
const counts = {
|
|
768
|
+
before: 0,
|
|
769
|
+
steps: 0,
|
|
770
|
+
after: 0
|
|
771
|
+
};
|
|
772
|
+
let stage;
|
|
773
|
+
for (const line of body.split("\n")) {
|
|
774
|
+
const header = line.match(/^ {2}(\w+):\s*$/);
|
|
775
|
+
if (header) {
|
|
776
|
+
stage = STAGES.find((candidate) => candidate === header[1]);
|
|
777
|
+
continue;
|
|
778
|
+
}
|
|
779
|
+
if (stage && /^ {4}- +(?:name|do):/.test(line)) counts[stage]++;
|
|
780
|
+
}
|
|
781
|
+
return counts;
|
|
782
|
+
};
|
|
783
|
+
/** The short name a test or suite is addressed by: `markdown` for plugin-markdown, `app` for APP.mdl. */
|
|
784
|
+
var shortName = (file) => file.match(/plugin-([\w-]+)\//)?.[1] ?? (file.endsWith("APP.mdl") ? "app" : file.replace(/\.mdl$/, ""));
|
|
785
|
+
var parseList = (value) => (value ?? "").split(",").map((item) => item.trim()).filter(Boolean);
|
|
786
|
+
/** Blocks of one kind in a document. Several blocks may share one fence, so headers are matched per line. */
|
|
787
|
+
var parseBlocks = (text, file, kind) => [...text.matchAll(/```mdl\n([\s\S]*?)```/g)].flatMap(([, fence]) => {
|
|
788
|
+
const headers = [...fence.matchAll(new RegExp(`^${kind}\\s+([\\w.-]+)\\s*(?::\\s*(.*))?$`, "gm"))];
|
|
789
|
+
return headers.map((header, index) => ({
|
|
790
|
+
file,
|
|
791
|
+
plugin: shortName(file),
|
|
792
|
+
id: header[1],
|
|
793
|
+
title: (header[2] ?? "").trim(),
|
|
794
|
+
body: fence.slice(header.index, headers[index + 1]?.index ?? fence.length)
|
|
795
|
+
}));
|
|
796
|
+
});
|
|
797
|
+
var parseTests = (text, file) => parseBlocks(text, file, "test").map(({ body, ...block }) => ({
|
|
798
|
+
...block,
|
|
799
|
+
status: body.match(/^\s*status:\s*(\w+)/m)?.[1] ?? "unverified",
|
|
800
|
+
actors: body.match(/^\s*actors:\s*([\w|\s]+?)\s*$/m)?.[1]?.trim() ?? "both",
|
|
801
|
+
stages: countStages(body),
|
|
802
|
+
covers: body.match(/^\s*covers:\s*\[(.*?)\]/m)?.[1] ?? "",
|
|
803
|
+
tags: parseList(body.match(/^\s*tags:\s*\[(.*?)\]/m)?.[1])
|
|
804
|
+
}));
|
|
805
|
+
var parseSuites = (text, file) => parseBlocks(text, file, "suite").map(({ body, ...block }) => ({
|
|
806
|
+
...block,
|
|
807
|
+
tags: parseList(body.match(/^\s*tags:\s*\[(.*?)\]/m)?.[1]),
|
|
808
|
+
tests: parseList(body.match(/^\s*tests:\s*\[(.*?)\]/m)?.[1]).map((ref) => {
|
|
809
|
+
const [plugin, id] = ref.includes(":") ? ref.split(":") : [block.plugin, ref];
|
|
810
|
+
return {
|
|
811
|
+
plugin,
|
|
812
|
+
id
|
|
813
|
+
};
|
|
814
|
+
})
|
|
815
|
+
}));
|
|
816
|
+
/**
|
|
817
|
+
* A dialect definition (`org.dxos.spec.*`) carries example tests to document its own syntax; those are illustrations,
|
|
818
|
+
* not plans, and listing them as runnable is a trap.
|
|
819
|
+
*/
|
|
820
|
+
var isDialect = (text) => /^id:\s*org\.dxos\.spec\./m.test(text.split("---")[1] ?? "");
|
|
821
|
+
/** The tests a suite names, in its order; a ref that resolves to nothing is reported as `missing`, not dropped. */
|
|
822
|
+
var resolveSuite = (tests, suite) => suite.tests.map((ref) => tests.find((candidate) => candidate.plugin === ref.plugin && candidate.id === ref.id) ?? {
|
|
823
|
+
file: suite.file,
|
|
824
|
+
plugin: ref.plugin,
|
|
825
|
+
id: ref.id,
|
|
826
|
+
title: "(unresolved)",
|
|
827
|
+
status: "missing",
|
|
828
|
+
actors: "both",
|
|
829
|
+
stages: {
|
|
830
|
+
before: 0,
|
|
831
|
+
steps: 0,
|
|
832
|
+
after: 0
|
|
833
|
+
},
|
|
834
|
+
covers: "",
|
|
835
|
+
tags: []
|
|
836
|
+
});
|
|
837
|
+
/** Selects the tests (or suites) a query names from the parsed documents. */
|
|
838
|
+
var selectQa = (documents, { query, tag, suite, suites: listSuites }) => {
|
|
839
|
+
const specs = documents.filter(({ text }) => !isDialect(text));
|
|
840
|
+
const tests = specs.flatMap(({ file, text }) => parseTests(text, file));
|
|
841
|
+
const suites = specs.flatMap(({ file, text }) => parseSuites(text, file));
|
|
842
|
+
const [plugin, testId] = query.length >= 2 ? query : [void 0, void 0];
|
|
843
|
+
const filter = query.length >= 2 ? void 0 : query[0];
|
|
844
|
+
const matchesPlugin = (item) => !plugin || item.plugin === plugin.replace(/^plugin-/, "");
|
|
845
|
+
const matchesFilter = (item) => !filter || `${item.file} ${item.id} ${item.title}`.toLowerCase().includes(filter.toLowerCase());
|
|
846
|
+
let selectedSuites = suites.filter(matchesPlugin).filter(matchesFilter);
|
|
847
|
+
if (Option.isSome(tag)) selectedSuites = suites.filter((candidate) => candidate.tags.includes(tag.value));
|
|
848
|
+
if (Option.isSome(suite)) selectedSuites = suites.filter((candidate) => candidate.id === suite.value);
|
|
849
|
+
const description = plugin ? `${plugin} ${testId}` : filter ?? Option.getOrUndefined(tag) ?? Option.getOrUndefined(suite);
|
|
850
|
+
if (listSuites) return {
|
|
851
|
+
selection: {
|
|
852
|
+
kind: "suites",
|
|
853
|
+
rows: selectedSuites
|
|
854
|
+
},
|
|
855
|
+
description
|
|
856
|
+
};
|
|
857
|
+
if (Option.isSome(tag) || Option.isSome(suite)) {
|
|
858
|
+
const seen = /* @__PURE__ */ new Set();
|
|
859
|
+
return {
|
|
860
|
+
selection: {
|
|
861
|
+
kind: "tests",
|
|
862
|
+
rows: selectedSuites.flatMap((candidate) => resolveSuite(tests, candidate)).filter((test) => {
|
|
863
|
+
const key = `${test.plugin}:${test.id}`;
|
|
864
|
+
return seen.has(key) ? false : (seen.add(key), true);
|
|
865
|
+
})
|
|
866
|
+
},
|
|
867
|
+
description
|
|
868
|
+
};
|
|
869
|
+
}
|
|
870
|
+
return {
|
|
871
|
+
selection: {
|
|
872
|
+
kind: "tests",
|
|
873
|
+
rows: tests.filter(matchesPlugin).filter(matchesFilter).filter((test) => !testId || test.id.toLowerCase() === testId.toLowerCase())
|
|
874
|
+
},
|
|
875
|
+
description
|
|
876
|
+
};
|
|
877
|
+
};
|
|
878
|
+
/** The numbered table `/dxos:qa` renders; row numbers are the addressing scheme. */
|
|
879
|
+
var formatSelection = (selection, description) => {
|
|
880
|
+
const noun = selection.kind;
|
|
881
|
+
if (selection.rows.length === 0) return [description ? `No ${noun} matching "${description}".` : `No ${noun} found.`];
|
|
882
|
+
if (selection.kind === "suites") {
|
|
883
|
+
const width = Math.max(...selection.rows.map((suite) => suite.id.length));
|
|
884
|
+
return selection.rows.flatMap((suite, index) => [`${String(index + 1).padStart(2)}. ${suite.id.padEnd(width)} ${String(suite.tests.length).padStart(2)} tests ${suite.title}`, ` ${suite.file}${suite.tags.length ? ` tags: ${suite.tags.join(", ")}` : ""}`]);
|
|
885
|
+
}
|
|
886
|
+
const idWidth = Math.max(...selection.rows.map((test) => test.id.length));
|
|
887
|
+
const statusWidth = Math.max(...selection.rows.map((test) => test.status.length));
|
|
888
|
+
return selection.rows.flatMap((test, index) => {
|
|
889
|
+
const { before, steps, after } = test.stages;
|
|
890
|
+
return [`${String(index + 1).padStart(2)}. ${test.plugin}:${test.id.padEnd(idWidth)} ${test.status.padEnd(statusWidth)} ${String(steps).padStart(2)} steps (${before} before, ${after} after) ${test.title}`, ` ${test.file}${test.covers ? ` covers: ${test.covers}` : ""}`];
|
|
891
|
+
});
|
|
892
|
+
};
|
|
893
|
+
/** Every `.mdl` file under `root`, sorted, with paths relative to it; broken symlinks are skipped. */
|
|
894
|
+
var readDocuments = Effect.fnUntraced(function* (root) {
|
|
895
|
+
const fs = yield* FileSystem.FileSystem;
|
|
896
|
+
const path = yield* Path.Path;
|
|
897
|
+
const walk = (dir) => Effect.gen(function* () {
|
|
898
|
+
const entries = (yield* fs.readDirectory(dir).pipe(Effect.orElseSucceed(() => []))).sort();
|
|
899
|
+
const files = [];
|
|
900
|
+
for (const entry of entries) {
|
|
901
|
+
if (SKIP.has(entry)) continue;
|
|
902
|
+
const full = path.join(dir, entry);
|
|
903
|
+
const info = yield* fs.stat(full).pipe(Effect.option);
|
|
904
|
+
if (Option.isNone(info)) continue;
|
|
905
|
+
if (info.value.type === "Directory") files.push(...yield* walk(full));
|
|
906
|
+
else if (entry.endsWith(".mdl")) files.push(full);
|
|
907
|
+
}
|
|
908
|
+
return files;
|
|
909
|
+
});
|
|
910
|
+
const files = yield* walk(root);
|
|
911
|
+
return yield* Effect.forEach(files, (file) => fs.readFileString(file).pipe(Effect.map((text) => ({
|
|
912
|
+
file: path.relative(root, file),
|
|
913
|
+
text
|
|
914
|
+
}))));
|
|
915
|
+
});
|
|
916
|
+
var list = Command.make("list", {
|
|
917
|
+
query: Argument.String("query").pipe(Argument.withDescription("`<plugin> <testId>` for exactly one test (`markdown QA-1`, `app QA-1`), or a substring filter."), Argument.variadic({ max: 2 })),
|
|
918
|
+
tag: Flag.String("tag").pipe(Flag.withDescription("The tests of every suite carrying this tag."), Flag.optional),
|
|
919
|
+
suite: Flag.String("suite").pipe(Flag.withDescription("The tests of one suite, in its order."), Flag.optional),
|
|
920
|
+
suites: Flag.Boolean("suites").pipe(Flag.withDescription("List suites instead of tests."), Flag.withDefault(false)),
|
|
921
|
+
json: Flag.Boolean("json").pipe(Flag.withDescription("Print the rows as JSON."), Flag.withDefault(false)),
|
|
922
|
+
root: Flag.String("root").pipe(Flag.withDescription("Directory to search (env DX_REPO_ROOT; default the working directory)."), Flag.withFallbackConfig(Config.String("DX_REPO_ROOT")), Flag.withDefault(process.cwd()))
|
|
923
|
+
}, Effect.fnUntraced(function* ({ json, root, ...query }) {
|
|
924
|
+
const { selection, description } = selectQa(yield* readDocuments(root), query);
|
|
925
|
+
if (json || (yield* JsonOutput)) {
|
|
926
|
+
yield* Console.log(JSON.stringify(selection.rows, null, 2));
|
|
927
|
+
return;
|
|
928
|
+
}
|
|
929
|
+
for (const line of formatSelection(selection, description)) yield* Console.log(line);
|
|
930
|
+
})).pipe(Command.withDescription("List the executable `test` and `suite` blocks across the .mdl specs, numbered."));
|
|
931
|
+
var qa = Command.make("qa").pipe(Command.withDescription("Deus.QA tools."), Command.withSubcommands([list, qaLint]));
|
|
932
|
+
//#endregion
|
|
933
|
+
//#region src/cli/index.ts
|
|
934
|
+
/** The `deus` command tree: run standalone by `bin/deus.ts` and mounted by the `dx` CLI as `dx deus`. */
|
|
935
|
+
var deus = Command.make("deus").pipe(Command.withDescription("Tools for Deus `.mdl` specs."), Command.withSubcommands([
|
|
936
|
+
changelog,
|
|
937
|
+
features,
|
|
938
|
+
index,
|
|
939
|
+
lint,
|
|
940
|
+
qa,
|
|
941
|
+
review
|
|
942
|
+
]));
|
|
943
|
+
//#endregion
|
|
944
|
+
export { ChangelogCheckError, DEFAULT_BASE_REF, FEATURE_STATUSES, FeatureCheckError, GitError, JsonOutput, LintError, QA_CHECKS, QaLintError, ReviewCheckError, WAIVER, analyzeFeatureMap, blockField, buildSpecIndex, changelog, checkChangelog, checkFeatures, checkReview, configDependsOn, deriveStatus, deus, featureTasks, features, findUnboundReferences, findUnsafeTeardowns, formatSelection, index, isDialect, itemsUnder, keyList, lint, lintFiles, lintQa, parseFeatureMap, parseSuites, parseTests, printIndex, qa, qaLint, readDocuments, review, reviewItems, reviewVerdicts, selectQa, shortName };
|
|
945
|
+
|
|
946
|
+
//# sourceMappingURL=cli.mjs.map
|