@taskless/cli 0.10.2 → 0.11.1

package/dist/rules/ast-grep-binary.d.ts

@@ -0,0 +1,26 @@
+import type { PlatformBinarySpec } from "./platform-binary";
+/**
+ * ast-grep's per-platform packaging, as the shared resolver understands it.
+ *
+ * `toolchainSuffix: true` is what produces `@ast-grep/cli-linux-x64-gnu` and
+ * `-win32-x64-msvc`. The Vale packages set it false; see
+ * {@link PlatformBinarySpec} for why that distinction is load-bearing.
+ *
+ * Both `ast-grep` and `sg` are listed because the wrapper declares them as bin
+ * entries for the same target, so either may be what got linked. `ast-grep`
+ * leads because it is the name the platform package ships the binary under; the
+ * resolver reverses the list at the link-based tiers, so `sg` is still tried
+ * first there and named in the PATH advice, as it was before the shared
+ * resolver existed.
+ *
+ * ## Why this sits in its own module rather than in `scan.ts`
+ *
+ * The spec is data: five fields describing how a package is named and how the
+ * binary identifies itself. `scan.ts` is the scanner — it reaches
+ * `rules/engines.ts`, and through it `node:fs/promises` and the CLI's error
+ * type. `@taskless/cli/node/runtimes` publishes this spec so a consumer can
+ * resolve the same binary the CLI executes, and a consumer that wants a path
+ * has no business loading a scanner to get one. Vale's spec is already a leaf
+ * for the same reason: `rules/vale/binary.ts` imports nothing but the resolver.
+ */
+export declare const AST_GREP_BINARY: PlatformBinarySpec;

package/dist/rules/capabilities.d.ts

@@ -0,0 +1,351 @@
+/**
+ * What the two local engines can actually read.
+ *
+ * PURE DATA, DELIBERATELY. This module is imported by `src/prompts/recipes.ts`,
+ * which is a Worker-safe library surface — no citty, no telemetry, no
+ * filesystem, no network — and `assert-prompts-graph` in `vite.config.ts`
+ * fails the build if the prompts chunk's graph reaches a host capability. So
+ * nothing here may read `package.json`, spawn a binary, or import a node
+ * builtin. The values are transcribed once, here, and pinned by tests that do
+ * spawn the binaries.
+ *
+ * THE BINARIES ARE THE ONLY AUTHORITY, and neither of them can be asked at
+ * render time:
+ *
+ * - `src/generated/ast-grep-rule-schema.json` types `$defs.Language` as a bare
+ *   string with no enum — its only hint is an `example` reading `"typescript"`,
+ *   which is not even the canonical spelling — so the vendored schema cannot
+ *   answer the question. `verify` answers it from the constants below instead
+ *   (see `validateLanguage` in `verify.ts`).
+ * - `detect --json` reports the *repository's* languages in a different
+ *   vocabulary — `C++` where ast-grep says `Cpp` — and says nothing about what
+ *   an engine can parse.
+ * - Vale self-reports nothing at all. Its reach was measured by probing the
+ *   shipped binary, which is why the Vale constants below carry a probe-shaped
+ *   contract test rather than a parsed capability listing.
+ *
+ * BUMPING AN ENGINE IS A ONE-FILE EDIT. Change the version constant and the
+ * list beside it; `test/ast-grep-vendor-contract.test.ts` and
+ * `test/vale-vendor-contract.test.ts` fail until the two agree, which is the
+ * whole point of transcribing rather than describing. See taskless/cli#151 for
+ * the routing miss this exists to prevent: two GitHub Actions workflow rules
+ * were escalated to `runtime` because nothing said ast-grep parses YAML.
+ */
+/**
+ * The ast-grep release pinned in `packages/cli/package.json`, both for
+ * `@ast-grep/cli` and for every `@ast-grep/cli-<platform>` optional dependency.
+ *
+ * Pinned against the binary by `test/ast-grep-vendor-contract.test.ts`
+ * ("engine capabilities" → "reports the pinned version").
+ */
+export declare const AST_GREP_VERSION = "0.45.2";
+/**
+ * Every language ast-grep can parse, verbatim from
+ * `sg run -h` → `Supported languages are: [...]` at
+ * {@link AST_GREP_VERSION}.
+ *
+ * SPELLINGS ARE ast-grep's, NOT ours and not `detect`'s. `Cpp`, `CSharp`,
+ * `JavaScript`, `Tsx` — a rule's `language:` field is handed to ast-grep
+ * unchanged, so the binary has the final opinion. MEASURED at 0.45.2: it
+ * accepts more than this list — case variants and a fixed set of extension
+ * aliases, both enumerated in {@link AST_GREP_LANGUAGE_ALIASES} — so an
+ * off-list spelling is not on its own an error. The two real failures are a
+ * name ast-grep does not know at all (`C#`), which aborts config parsing so
+ * every rule goes unreported, and a valid name for the wrong parser
+ * (`TypeScript` over `.tsx`), which reports nothing and reads as a clean
+ * codebase. `verify` catches both; see `verify.ts`.
+ *
+ * Pinned by set-equality against the binary in
+ * `test/ast-grep-vendor-contract.test.ts`, so a version bump that adds or drops
+ * a language fails there rather than silently narrowing what the router
+ * believes is buildable locally.
+ */
+export declare const AST_GREP_LANGUAGES: readonly ["Bash", "C", "Cpp", "CSharp", "Css", "Dart", "Elixir", "Go", "Haskell", "Hcl", "Html", "Java", "JavaScript", "Json", "Kotlin", "Lua", "Markdown", "Nix", "Php", "Python", "Ruby", "Rust", "Scala", "Solidity", "Swift", "Tsx", "TypeScript", "Yaml"];
+/** One of the spellings {@link AST_GREP_LANGUAGES} lists, canonically cased. */
+export type AstGrepLanguage = (typeof AST_GREP_LANGUAGES)[number];
+/**
+ * The spellings ast-grep also accepts that are not on the canonical list,
+ * mapped to the language each resolves to.
+ *
+ * Keys are lowercase because ast-grep's own matching is case-insensitive:
+ * `TYPESCRIPT`, `Cs` and `GOLANG` all resolve at 0.45.2. That makes the whole
+ * accepted vocabulary "the canonical list plus these, compared lowercased",
+ * which is what {@link resolveAstGrepLanguage} implements.
+ *
+ * Every value here was probed through a real config, because that is the only
+ * thing a rule file is ever fed to. That is deliberate: `sg run --lang` is a
+ * SEPARATE vocabulary and cannot stand in for this one. MEASURED at 0.45.2,
+ * the two agree on `C++` and `cxx` (both accepted) and on `C#` (both
+ * rejected), but `--lang` rejects with clap's own `is not supported!` before
+ * a rule is ever read, so it exercises a different code path and is not
+ * evidence about `language:`. At 0.41.0 they diverged outright: `--lang C++`
+ * was rejected while `language: C++` parsed. Nothing here probes `--lang`.
+ *
+ * THIS IS THE ONE LIST HERE THE BINARY CANNOT BE ASKED TO ENUMERATE. `sg run
+ * -h` prints the canonical list, so `AST_GREP_LANGUAGES` above is checked by
+ * set-equality against it; nothing prints the aliases. Each entry is instead
+ * pinned by *probing*, in the "language aliases" suite of
+ * `test/ast-grep-vendor-contract.test.ts`: every key is fed to the binary in a
+ * config and the resolution is read back out of the scan stream's own
+ * `language` field — ast-grep reports the canonical name it settled on, so the
+ * mapping is the binary's answer rather than ours. The same suite feeds a
+ * sweep of near-misses (`h`, `mjs`, `sh`, `tf`, `csx`) and asserts they are
+ * rejected, so a bump that ADDS an alias fails there too.
+ *
+ * Whitespace is not folded, deliberately: `language: "ts "` is rejected by the
+ * binary, so accepting it here would pass a rule that cannot run.
+ */
+export declare const AST_GREP_LANGUAGE_ALIASES: Readonly<Record<string, AstGrepLanguage>>;
+/**
+ * The language ast-grep would parse `spelling` as, or `undefined` if it would
+ * reject the config outright.
+ *
+ * `undefined` is the fatal case, not a stylistic one: an unrecognized name
+ * fails `SgLang` deserialization, which aborts parsing of the single config
+ * Taskless assembles for the run — so every *other* sg rule goes unreported
+ * with it.
+ */
+export declare function resolveAstGrepLanguage(spelling: string): AstGrepLanguage | undefined;
+/**
+ * The `.ts` / `.tsx` split — the one pair of ast-grep languages that share a
+ * family and read disjoint file extensions.
+ *
+ * MEASURED at 0.45.2: a `TypeScript` rule over a `.tsx` tree exits zero having
+ * matched nothing, and a `Tsx` rule scans `.tsx` only. That is the quiet
+ * failure of the two, because "no findings" is exactly what a clean codebase
+ * looks like. Pinned by "treats Tsx and TypeScript as different parsers, not
+ * aliases" in `test/ast-grep-vendor-contract.test.ts`.
+ *
+ * Kept to this pair deliberately. Every other language's extensions would be a
+ * second vendored table with no measured backing, and the trap only exists
+ * where two languages look like spellings of one thing.
+ */
+export declare const AST_GREP_TSX_SPLIT: Readonly<Partial<Record<AstGrepLanguage, string>>>;
+/**
+ * The Vale release carried by the `@taskless/vale-<platform>` packages pinned
+ * in `packages/cli/package.json`. Their npm versions append a build stamp,
+ * `<valeVersion>-<yyyymmddhhmmss>`, minted per publish by
+ * `.github/workflows/release-vale.yml`; this is the version Vale itself
+ * reports.
+ *
+ * The SHAPE rather than an example, deliberately. A literal stamp here has to
+ * be hand-carried on every bump, and it has gone one release out of date twice
+ * now, which is worse than no example: it reads as the current pin and is not
+ * one. The real value lives in `packages/cli/package.json`, where a reader can
+ * see all six at once and cannot be told a stale one.
+ *
+ * Pinned against the binary by `test/vale-vendor-contract.test.ts`
+ * ("engine capabilities" → "reports the pinned version").
+ */
+export declare const VALE_VERSION = "3.20.0";
+/**
+ * Which tier Vale routes an extension to.
+ *
+ * `converter:<program>` carries the program's own name in the tier, so one
+ * table row states both the tier and the thing a user would install. The name
+ * is the one Vale prints in its `E100` text, because that is the string a
+ * reader will search for.
+ */
+export type ValeFormatTier = 
+/** Parsed in-process: the document is prose, its own syntax is skipped. */
+"markup"
+/** Parsed in-process: comment text is linted, the code body is invisible. */
+ | "comment"
+/** No parser: the whole file is linted as one block of prose. */
+ | "plaintext"
+/** Vale shells out to a program the `@taskless/vale-*` packages do not ship. */
+ | `converter:${string}`;
+/**
+ * EVERY MEASURED VALE EXTENSION, AND ITS TIER. THE ONLY TABLE.
+ *
+ * Adding an extension is one line here; every list, glob, notice and test below
+ * derives from this record, so there is no second place to keep in step. Two
+ * branches once measured this independently and produced two tables that
+ * disagreed about six extensions — that is what this single record exists to
+ * make impossible.
+ *
+ * MEASURED, NOT DOCUMENTED, AND MEASURED BY A DISCRIMINATING PROBE. Ordinary
+ * prose fires in all three readable tiers, so it can never separate them. Each
+ * tier is pinned by the property only that tier has, in
+ * `test/vale-vendor-contract.test.ts`:
+ *
+ * - **markup** — a construct only a real parser skips yields ZERO (a fenced
+ *   code block, an Org `#` line, an HTML comment).
+ * - **comment** — the token in a comment yields one finding and the same token
+ *   on a bare non-comment line yields ZERO. A type that fires on both is the
+ *   plaintext fallback wearing a code extension.
+ * - **plaintext** — a bare line yields a finding. Listed only where the tier is
+ *   surprising: `.tex`, `.mkd` and `.mkdn` all look like markup and are not.
+ *   Everything unnamed lands here too, which is why this tier does not need to
+ *   be exhaustive.
+ * - **converter** — a non-zero exit whose output carries `E100` and the
+ *   program's name.
+ *
+ * Measured spellings, not families. `.mdown` is native Markdown and `.mkd` and
+ * `.mkdn` are not; `.asc` is a third AsciiDoc spelling that crashes exactly
+ * like `.adoc`; `.ditamap` is plaintext while `.dita` needs `dita`. Case is
+ * part of the key — `.r` and `.R` were both measured, `.PY` was measured and is
+ * not comment-aware. Add a row only after probing it; the contract test refuses
+ * to take one on faith.
+ *
+ * A VERSION BUMP INVALIDATES THIS TABLE — RE-MEASURE THE WHOLE OF IT. The tiers
+ * are a property of {@link VALE_VERSION}'s binary, and the dangerous direction
+ * is a format Vale *learns*: an extension missing from this table is read as
+ * plain text today, but the moment Vale routes it to a converter the same
+ * omission is a crash that takes down every Vale rule in the run.
+ *
+ * NOTHING MOVED ACROSS 3.19.0 → 3.20.0, AND THE SECOND HALF OF THAT CLAIM IS
+ * THE ONE THAT COST SOMETHING. Every row below was re-probed against the
+ * 3.20.0 binary and none of them moved, which this table can report. It cannot
+ * report a format Vale *learned*, so that direction was checked at the source
+ * instead: the v3.19.0...v3.20.0 tree adds no `internal/lint/<format>.go` and
+ * no `internal/lint/code/<lang>.go`, and every existing one of those files
+ * changes by a single import line from the org rename. No format was learned,
+ * so there is no new row to add. Do that check on the next bump too — a green
+ * table is silence about the dangerous direction, not evidence against it.
+ *
+ * THE TABLE ALSO HELD ACROSS 3.18.0 → 3.19.0, AND THAT IS NOT THE SAME AS THE
+ * BUMP BEING FREE. Every row below was re-probed against the 3.19.0 binary and
+ * not one of them moved. What moved was a format Vale *learned*, which is
+ * precisely the case a table of existing rows cannot report: `.ex` and `.exs`
+ * gained comment and doc-attribute extraction, so they left the unnamed
+ * plaintext fallback for the `comment` tier and are new rows below.
+ *
+ * Read that direction carefully, because it is a narrowing rather than a gain.
+ * On 3.18.0 an Elixir file was linted as one block of prose, so a rule matching
+ * `[*.ex]` fired on identifiers and string literals as readily as on comments.
+ * On 3.19.0 the code body is invisible and only comments and `@doc` attributes
+ * are read. Findings disappear, no error is raised, and nothing but a re-probe
+ * would have told us. A format Vale learns is never a no-op: the benign version
+ * of it is this one, and the dangerous version is a converter (see `.typ`).
+ *
+ * `.mdx` stayed `markup` and changed underneath the tier: a JSX element's
+ * children are now read as the Markdown they are, so a Vale rule covers prose
+ * inside `<Steps>` or `<Aside>` that it previously skipped, and those children
+ * carry the element name as a `text.class.<name>` scope. The tier is the wrong
+ * instrument for that kind of change — it says a parser exists, not what the
+ * parser sees — which is the second reason a bump needs more than this table.
+ *
+ * The 3.17.1 → 3.18.0 bump is what the dangerous case looks like in practice.
+ * Every row was re-probed against the 3.18.0 binary then too, and eight moved,
+ * in three different directions — which is why "re-measure" is not boilerplate:
+ *
+ * - `.mdx` gained a native parser: `converter:mdx2vast` → `markup`. It is
+ *   supported now, and `[*.{md,mdx}]` is a legitimate matcher again.
+ * - `.typ` gained a parser that shells out to `typst2vast`
+ *   (https://docs.vale.sh/formats/typst): `plaintext` →
+ *   `converter:typst2vast`. That is the dangerous direction — 3.17.1 read it as
+ *   prose, and the same row on 3.18.0 crashes the run. It stays unsupported
+ *   permanently, since we do not support formats needing an external program.
+ * - `.rmd` gained a real Markdown parser, so it left the "looks like markup and
+ *   is not" list above: `plaintext` → `markup`.
+ * - `.qml` and `.scss` gained parsers that see their comments: `plaintext` →
+ *   `comment`. Vale's docs had claimed both for years; on 3.17.1 the claim was
+ *   measurably false and on 3.18.0 it is true.
+ * - `.qmd` (Quarto) and `.myst` (MyST) measured as `markup`, and `.qdoc` as
+ *   `comment` — QDoc documentation lives in a doc-comment block, so it is
+ *   comment extraction rather than the markup tier a first reading of the
+ *   release notes suggests, and probing it with bare prose reads as no support
+ *   at all. All three are new rows, none of them reachable on 3.17.1.
+ *
+ * PHP also changed without the release notes saying so: comment extraction now
+ * needs a real `<?php` tag, where 3.17.1 linted a bare `//` comment without
+ * one. The tier did not move, but the probe had to. Re-probe every row on the
+ * next bump, by the discriminating property and by each language's own comment
+ * syntax — a wrong delimiter reads exactly like absent support.
+ */
+export declare const VALE_FORMAT_TIERS: Readonly<Record<string, ValeFormatTier>>;
+/**
+ * Extensions Vale parses as markup: the whole document is prose, and the
+ * format's own non-prose constructs are excluded.
+ *
+ * The HTML entries carry a consequence worth stating to an author: prose
+ * outside an element is not linted, so a bare sentence in a `.html` file yields
+ * nothing.
+ */
+export declare const VALE_MARKUP_EXTENSIONS: readonly string[];
+/**
+ * Extensions where Vale lints **comment text only** and ignores the code body.
+ */
+export declare const VALE_COMMENT_EXTENSIONS: readonly string[];
+/**
+ * Extensions measured into the plaintext fallback whose spelling suggests
+ * otherwise.
+ *
+ * Not exhaustive and not meant to be — every unnamed extension is plaintext
+ * too. These are the ones an author would reasonably assume were parsed, so
+ * they are worth naming in a recipe rather than leaving to "everything else".
+ */
+export declare const VALE_PLAINTEXT_EXTENSIONS: readonly string[];
+/**
+ * The converter each converter-dependent extension needs, keyed by extension.
+ *
+ * The lookup `rules/vale/formats.ts` uses to name a converter in the skip
+ * notice. Keys are lowercase because every measured converter format is; a
+ * caller comparing an extension off the filesystem must lowercase it first, or
+ * `README.RST` becomes a crash on case-insensitive platforms only.
+ */
+export declare const VALE_CONVERTER_BY_EXTENSION: Readonly<Record<string, string>>;
+/** A format Vale supports upstream but cannot read without an external tool. */
+export interface ValeConverterFormat {
+    /** Extensions Vale routes through this converter. */
+    extensions: readonly string[];
+    /** The executable or artifact Vale looks for, named in its own E100 text. */
+    converter: string;
+}
+/**
+ * Formats that fail rather than lint, because Vale shells out to a converter
+ * this CLI does not ship.
+ *
+ * SAY THIS ACCURATELY: Vale supports these formats. What is missing is the
+ * external program it delegates the parse to. The failure is environmental, and
+ * describing it as "Vale does not support reStructuredText" sends an author
+ * looking for the wrong fix.
+ *
+ * The blast radius is what makes this worth surfacing at routing time rather
+ * than at authoring time: Vale exits 2 with an `E100` runtime error and
+ * abandons the run, and `--no-exit` does not suppress it. One `.typ` file
+ * caught by a rule's glob takes down the entire Vale pass, including every
+ * other rule and every other file — so `[*.{md,typ}]` is not a slightly wider
+ * matcher than `[*.md]`, it is a broken one. (`[*.{md,mdx}]` was that example
+ * until 3.18.0 gave MDX a native parser — the membership of this tier is a
+ * property of {@link VALE_VERSION}, and so is the worked example.)
+ */
+export declare const VALE_CONVERTER_DEPENDENT: readonly ValeConverterFormat[];
+/**
+ * Vale's checker tag per converter-dependent extension, from the `E100` text.
+ *
+ * This is the host-independent half of the failure. The prose after the tag is
+ * not: `.xml` reports `xsltproc not found` where the program is absent and
+ * `no XSLT transform provided` where it is present, and the two are split by
+ * platform — macOS ships `/usr/bin/xsltproc`, the Linux CI image does not. A
+ * contract test that matched on the program name therefore passed locally and
+ * failed in CI, which is how this list came to exist.
+ *
+ * `.xml` is also the one entry whose converter is not sufficient on its own. An
+ * XSLT transform is document-specific, so there is no default to ship and
+ * installing `xsltproc` does not make `.xml` lintable — unlike `asciidoctor`,
+ * which genuinely fixes `.adoc`. That is why its `converter` names the
+ * stylesheet as well as the program.
+ */
+export declare const VALE_CONVERTER_CHECKERS: Readonly<Record<string, string>>;
+/** Every converter-dependent extension, flattened. */
+export declare const VALE_CONVERTER_DEPENDENT_EXTENSIONS: readonly string[];
+/** `Bash, C, Cpp, …` — the ast-grep language list as recipe prose. */
+export declare function astGrepLanguageList(): string;
+/** `.htm, .html, …` — Vale's markup extensions as recipe prose. */
+export declare function valeMarkupList(): string;
+/** `.c, .c++, …` — Vale's comment-only extensions as recipe prose. */
+export declare function valeCommentList(): string;
+/**
+ * `.mkd, .mkdn, …` — the plaintext extensions worth naming, as recipe prose.
+ *
+ * Rendered rather than written into the recipe because the surprising cases are
+ * exactly the ones a hand-written list gets wrong.
+ */
+export declare function valePlaintextList(): string;
+/**
+ * `.rst (needs rst2html), …` — Vale's converter-dependent formats as recipe
+ * prose, each naming the tool whose absence is the actual failure.
+ */
+export declare function valeConverterList(): string;

package/dist/rules/constraints.d.ts

@@ -0,0 +1,132 @@
+import type { EngineName } from "./layout";
+/**
+ * What `verify` enforces beyond the engine's own schema.
+ *
+ * ## Why this exists
+ *
+ * A rule the engine executes correctly can still be refused. Those refusals are
+ * deliberate, but they are OURS, and a generator that never reads our recipes
+ * cannot know them. Published in the conformance corpus so an external eval can
+ * tell "your rule is wrong about the subject" from "your rule broke a house
+ * rule it was never told about" — two findings that want completely different
+ * responses.
+ *
+ * ## Why every entry has a test that triggers it
+ *
+ * A hand-maintained list of what code does goes stale, and this is not
+ * hypothetical: `create-sg-rule.md` told agents for months that
+ * "`verify` never reads `language`", which stopped being true when
+ * `validateLanguage` landed. Nothing failed, because prose has no test.
+ *
+ * `test/constraints.test.ts` builds a rule that violates each entry and
+ * asserts `verify` rejects it, keyed on `id`. An entry describing a check that
+ * no longer fires fails the suite; a check with no entry is invisible to that
+ * test and is the gap this list is trying to close, so add one when you add a
+ * check.
+ */
+export interface RuleConstraint {
+    /** Stable key. Consumers branch on this; renaming is breaking. */
+    id: string;
+    engine: EngineName;
+    /**
+     * Which command refuses the rule.
+     *
+     * Load-bearing for a consumer's eval ORDER, not a detail. A `verify`
+     * constraint is decided from the files alone and can be checked before
+     * anything runs; a `test` constraint needs the fixtures to execute. Running
+     * the cross-comparison before `verify` passes measures the wrong thing, and
+     * treating a `test`-time refusal as a `verify` gap sends someone to the wrong
+     * layer.
+     *
+     * The split is not always where it looks. `verify` requires that a test FILE
+     * exists, by filename; whether that file is attributed to this rule is
+     * decided later, from the `id:` inside it.
+     */
+    enforcedBy: "verify" | "test";
+    /** One line, for a report that lists several. */
+    summary: string;
+    /** Why it exists, so a reader can tell a house rule from a bug. */
+    rationale: string;
+}
+/**
+ * One constraint a rule broke, paired with the message that reports it.
+ *
+ * Emitted alongside `errors` rather than replacing it. A consumer mapping a
+ * rejection back to the rationale we already wrote had only our wording to
+ * match on, and wording is not a contract: rephrasing an error message is not
+ * a breaking change, so a text match rots without anything reporting it.
+ *
+ * The message is repeated rather than joined to `errors` by index. An index
+ * join is a contract nobody can see, and it breaks the first time either side
+ * filters or reorders. Repeating the string lets a consumer ignore `errors`
+ * entirely.
+ */
+export interface RuleViolation {
+    constraintId: RuleConstraintId;
+    message: string;
+}
+export declare const RULE_CONSTRAINTS: readonly [{
+    readonly id: "sg-id-matches-directory";
+    readonly engine: "sg";
+    readonly enforcedBy: "verify";
+    readonly summary: "A rule's `id:` must equal the directory it lives in.";
+    readonly rationale: "The directory name is the rule id: it is what `check` and `test` address, and what a person types to delete a rule. ast-grep registers the rule under the id in its body. With the two apart, `test` cannot find the rule at all, and `check` does run it but reports findings under a name no directory has, so nobody can locate what produced them.";
+}, {
+    readonly id: "sg-regex-needs-kind";
+    readonly engine: "sg";
+    readonly enforcedBy: "verify";
+    readonly summary: "A `regex` needs a sibling `kind`, in `rule`, `constraints` and `utils`.";
+    readonly rationale: "A regex match with no kind to anchor it is ambiguous and slow: it is applied to every node rather than to the one shape the author meant. ast-grep accepts it, so the engine is not the thing that will tell you.";
+}, {
+    readonly id: "sg-language-accepted";
+    readonly engine: "sg";
+    readonly enforcedBy: "verify";
+    readonly summary: "`language:` must be a spelling ast-grep itself uses; a resolvable but non-canonical one is a notice.";
+    readonly rationale: "An unrecognized name aborts config parsing, which takes every other sg rule in the project down with it and reports nothing. That is the loudest possible failure with the quietest possible symptom: a clean report.";
+}, {
+    readonly id: "sg-files-globs-parse";
+    readonly engine: "sg";
+    readonly enforcedBy: "verify";
+    readonly summary: "`files:` globs must not name `.tsx` under TypeScript, or `.ts` under Tsx.";
+    readonly rationale: "A glob naming an extension the language cannot parse matches nothing, so the rule reports a clean codebase rather than an error. Only the TypeScript/Tsx pair is checked, and deliberately so: they are separate parsers rather than aliases, which is the one language/extension mismatch decidable from the rule file alone. No other extension is compared against `language`, so this is narrower than it first reads.";
+}, {
+    readonly id: "sg-required-fields";
+    readonly engine: "sg";
+    readonly enforcedBy: "verify";
+    readonly summary: "`id`, `language`, `severity`, `message` and `rule` are required.";
+    readonly rationale: "ast-grep needs fewer of these than we do. The extras are what make a finding actionable and a rule addressable once it is on disk.";
+}, {
+    readonly id: "sg-test-file-required";
+    readonly engine: "sg";
+    readonly enforcedBy: "verify";
+    readonly summary: "A rule must ship at least one test file under `.tests/`.";
+    readonly rationale: "A rule with no fixtures has shown neither that it fires nor that it stays quiet. `verify` requires the file; `test` requires the cases inside it to cover both.";
+}, {
+    readonly id: "sg-fixture-id-matches-rule";
+    readonly engine: "sg";
+    readonly enforcedBy: "test";
+    readonly summary: "A test file's own `id:` must equal the rule id.";
+    readonly rationale: "Fixtures are attributed by the id inside the file, not by its name. A fixture carrying another rule's id is silently not counted, so a rule that ships one reads as a rule that shipped none. `verify` passes, because the FILE is there; `test` is where it bites.";
+}];
+/**
+ * The id of a constraint this CLI publishes.
+ *
+ * Derived from the list rather than declared beside it, so a violation can only
+ * name a constraint that is actually published. Attributing a rejection to an
+ * id no consumer can look up would be worse than attributing nothing.
+ */
+export type RuleConstraintId = (typeof RULE_CONSTRAINTS)[number]["id"];
+/**
+ * Record an attributable failure in both places at once.
+ *
+ * `errors` stays the complete list and `violations` the attributable subset, so
+ * a consumer reading only `errors` sees exactly what it saw before this
+ * existed. Written through one call because two arrays maintained separately is
+ * how the message in one comes to differ from the message in the other.
+ */
+export declare function violate(target: {
+    errors: string[];
+    violations: RuleViolation[];
+}, constraintId: RuleConstraintId, message: string): void;
+/** Constraints for one engine. */
+export declare function constraintsFor(engine: EngineName): readonly RuleConstraint[];

package/dist/rules/layout.d.ts

@@ -0,0 +1,152 @@
+/**
+ * The rule layout table — the single description of what a rule is made of and
+ * where its files go, for every engine.
+ *
+ * SPLIT OUT OF `engines.ts` SO IT CAN BE PUBLISHED. This module holds data and
+ * nothing else: no filesystem, no network, no command tree. `engines.ts` keeps
+ * the helpers that join these values to a `cwd`, because those import
+ * `node:fs/promises` and a Worker cannot load them.
+ *
+ * The split exists because the Cloud Generator builds rule payloads against
+ * this table. While it lived only in prose, the same layout was described in
+ * seven stale code comments and in `cli-runtime-rule-execution`'s own spec text,
+ * all naming a path two migrations had already moved — and one of those stale
+ * comments put the wrong layout into a cross-team design document. A shape
+ * described in prose drifts in every place it is described, including the one
+ * that is supposed to be authoritative. Published as data, it cannot.
+ *
+ * Re-exported for consumers as `@taskless/cli/layout` (see `src/layout/`).
+ */
+/**
+ * Engines this CLI knows. The directory name under `.taskless/rules/` **is**
+ * the engine: dispatch reads the path and never parses a rule file to decide
+ * who owns it.
+ */
+export declare const ENGINES: readonly ["sg", "vale", "runtime"];
+export type EngineName = (typeof ENGINES)[number];
+/**
+ * How a rule's fixtures group into cases.
+ *
+ * Stated here rather than left implicit in each engine's fixture reader, which
+ * is where it lived: `runtime/fixtures.ts` rejects a loose file because a case
+ * is a directory, `vale/verify.ts` rejects a nested directory because a case is
+ * a document, and `verify.ts` counts ast-grep's own `valid:`/`invalid:` keys.
+ * The fact was recoverable only by reading three rejections, so every consumer
+ * transcribed it — which is what published this table in the first place.
+ *
+ * Each value is pinned beside the rejection that implements it, rather than in
+ * a test of its own: `runtime-fixtures.test.ts` asserts `case-directories`
+ * where it proves a loose file is refused, `vale-verify.test.ts` asserts
+ * `case-documents` where it proves a nested directory is refused, and
+ * `reference.test.ts` asserts `ast-grep-test` publishes no cases. A reader
+ * changing a reader's mind about its layout meets the declaration in the same
+ * test, which a separate file would not have achieved.
+ */
+export type FixtureLayout = 
+/** A case is a directory under `pass/` or `fail/`, handed to the check as its root. */
+"case-directories"
+/** A case is one document under `pass/` or `fail/`. */
+ | "case-documents"
+/** Not a directory layout: `valid:`/`invalid:` keys inside one ast-grep test file. */
+ | "ast-grep-test";
+/** How a rule reaches execution, or `null` when this CLI has no executor yet. */
+export type EngineExecutor = "ast-grep" | "vale-runner" | "runtime-harness" | null;
+export interface EngineLayout {
+    engine: EngineName;
+    /**
+     * The file inside a rule directory that *is* the rule, as a function of the
+     * rule id. `sg` and `vale` name it after the rule; `runtime` always calls it
+     * `check.ts`, because the rule is a program rather than a document.
+     */
+    ruleFile: (ruleId: string) => string;
+    /**
+     * The engine's per-rule config file, or `undefined` where the engine has
+     * nothing to put in one.
+     *
+     * Only Vale has one, and not for symmetry: Vale cannot express a rule's scope
+     * inside the style file — measured, it rejects unknown keys with `E201` — so
+     * scope needs somewhere else to live. ast-grep carries `files`/`ignores`
+     * inside the rule itself, so an `sg` per-rule config would be a file every
+     * author creates, no author fills, and every reader learns to ignore.
+     */
+    ruleConfigFile: string | undefined;
+    /** Subdirectory holding ast-grep capture rules, for engines that use them. */
+    capturesDirectory: string | undefined;
+    /** How this engine's fixtures group into cases. See {@link FixtureLayout}. */
+    fixtureLayout: FixtureLayout;
+    executor: EngineExecutor;
+}
+/**
+ * Everything defining a rule lives in one directory,
+ * `.taskless/rules/<engine>/<id>/`, the same shape for every engine. A rule is
+ * therefore one path — which is what lets `verify` and `test` take a path
+ * instead of an id, and what makes deleting a rule an `rm -rf` of one thing.
+ */
+export declare const RULES_DIRECTORY = "rules";
+/**
+ * The directory the whole tree hangs off, relative to the project root.
+ *
+ * Here rather than beside its callers because the conformance corpus publishes
+ * `.taskless/rules/<engine>/<id>/` as a path a consumer can act on, and a
+ * published path needs one value to be generated from.
+ *
+ * It is not yet the only copy. The literal appears in about fifteen places
+ * behind four constants that do not know about each other — `CANONICAL_DIR` in
+ * `install/install.ts` and `install/canonical.ts`, `TASKLESS_DIR` in
+ * `install/state.ts`, `TASKLESS_DIRECTORY` in `rules/scan.ts` and
+ * `rules/vale/formats.ts`. `rulesRoot` reads this one, so what the corpus
+ * publishes is what the rule commands resolve. Converging the rest is a
+ * tidy-up, and doing it inside a contract change would hide the contract
+ * change inside a rename.
+ */
+export declare const TASKLESS_DIRECTORY = ".taskless";
+/**
+ * A rule's tests, relative to its rule directory. **The dot is load-bearing.**
+ *
+ * ast-grep's `ruleDirs` recurses and parses every `.yml` beneath it as a rule,
+ * so a plain `tests/` directory inside a rule directory fails the entire scan
+ * with `Fail to parse yaml as RuleConfig: missing field 'language'`. Measured
+ * against ast-grep 0.41.0: `tests/` and `__tests__/` both hard-fail,
+ * a dot-directory is skipped by rule discovery, and `sg test` still reads it
+ * when `testDir` names it.
+ *
+ * That is undocumented behavior, and three things make depending on it
+ * acceptable. The failure is loud — a parse error naming the file, never a test
+ * silently reinterpreted as a rule. `ast-grep-vendor-contract.test.ts` pins it
+ * alongside the rest of ast-grep's observed behavior, so it is
+ * checked on every run rather than remembered. And the binary is pinned to an
+ * exact version, so it cannot change without a deliberate bump, which is
+ * exactly where that test fires.
+ *
+ * If it ever does break, the recorded fallback is to materialize a rules-only
+ * tree for ast-grep and point `ruleDirs` at that (design D2).
+ */
+export declare const RULE_TESTS_DIRECTORY = ".tests";
+export declare const ENGINE_LAYOUTS: {
+    sg: {
+        engine: "sg";
+        ruleFile: (ruleId: string) => string;
+        ruleConfigFile: undefined;
+        capturesDirectory: undefined;
+        fixtureLayout: "ast-grep-test";
+        executor: "ast-grep";
+    };
+    vale: {
+        engine: "vale";
+        ruleFile: (ruleId: string) => string;
+        ruleConfigFile: string;
+        capturesDirectory: undefined;
+        fixtureLayout: "case-documents";
+        executor: "vale-runner";
+    };
+    runtime: {
+        engine: "runtime";
+        ruleFile: () => string;
+        ruleConfigFile: undefined;
+        capturesDirectory: string;
+        fixtureLayout: "case-directories";
+        executor: "runtime-harness";
+    };
+};
+/** Whether `value` names an engine this CLI knows. */
+export declare function isKnownEngine(value: string): value is EngineName;