@nielspeter/eess-ts 0.2.1 → 0.5.0

package/dist/cli/commands/doctor.js

@@ -0,0 +1,224 @@
+import { diagnose } from '../../core/diagnose.js';
+import { isArchRuleError } from '@nielspeter/eess';
+import { loadRuleFiles } from '../load-rules.js';
+import { writeStderr } from '@nielspeter/eess/internal';
+import { orphanExclusions } from '../../core/orphan-exclusions.js';
+/**
+ * Report what each rule cannot enforce, without evaluating their conditions.
+ *
+ * It DOES materialize each rule's selection, as of plan 0096: "this rule examined
+ * nothing" is a fact about the selection, and the preview for 0098's floor has to
+ * read the same computation the floor will. The docstring used to say "without
+ * running any of them" and that stopped being true.
+ *
+ * **Supported and scoped** since plan 0077, which settled the keep-or-retire
+ * question 0069 left open. It diagnoses rule files the CLI can **load** — the
+ * `arch.rules.ts` shape `init` scaffolds, which `getting-started.md` calls the
+ * default path. Rules hosted in a vitest or jest file cannot be imported outside
+ * their runner; `diagnose()` is the answer there and reports the same findings.
+ *
+ * **Why the command earns its slot:** a **dead glob**. A rule whose selector can
+ * never match certifies nothing, and `check` never calls `diagnose()` — measured,
+ * `check` exits 0 with no output on such a rule while this reports it and exits
+ * 1. Until 0069's R3b turns that into a check-time failure, this and `diagnose()`
+ * are the only surfaces that see it.
+ *
+ * Not a build gate (0069): `check` is the gate.
+ */
+export async function runDoctor(args) {
+    if (args.ruleFiles.length === 0) {
+        writeStderr('Error: no rule files. Pass them as arguments or set `rules` in your config.\n');
+        return 1;
+    }
+    // Per file, not one flat array. `diagnose()` treats rules independently, so
+    // the results are identical — but the loop is the only place that knows which
+    // file a rule came from, and flattening first discarded it (bug 0026).
+    const findings = [];
+    const rules = [];
+    // Identities, never totals (docs/cli.md): a boolean told a JSON consumer that
+    // something failed without saying which file or why, leaving them to scrape
+    // stderr prose they do not read.
+    const loadFailures = [];
+    for (const file of args.ruleFiles) {
+        try {
+            const loaded = await loadRuleFiles([file]);
+            rules.push(...loaded);
+            findings.push(...diagnose(loaded).map((f) => ({ ...f, ruleFile: file })));
+        }
+        catch (error) {
+            // A rule file that self-executes a throwing `.check()` at import is a
+            // documented shape, and `runCheck` already tolerates it. Without this,
+            // `doctor` — the pre-flight R3b's gate depends on — crashes on the
+            // commonest legacy rule-file shape and abandons every remaining file,
+            // so the gate cannot be run on the population it was invented for.
+            // `loadRuleFiles` accumulates into a local array and returns it only
+            // after its own loop, so when the import throws NOTHING from that file
+            // survives. Saying "diagnosing what loaded" would be false, and
+            // swallowing it silently turned a visible crash into `exit 0` plus a
+            // clean bill of health — the ADR-009 rule 1 failure this command exists
+            // to surface, committed by the command.
+            //
+            // Two loud shapes (plan 0070 round 2): an ArchRuleError means the file
+            // self-executes a failing rule at import; anything else — measured, a
+            // raw TypeError from importing a vitest test file — used to crash the
+            // whole command and abandon every remaining file.
+            if (isArchRuleError(error)) {
+                writeStderr(`Error: ${file} executes its rules at import and threw, so none of it could be ` +
+                    `diagnosed. Leave builders un-terminated in a rule file (see docs/running-in-tests).\n`);
+            }
+            else {
+                // The remedy is CONDITIONAL: this branch fires for any load failure —
+                // a syntax error, a missing dependency — and asserting "this imports a
+                // test runner" unconditionally would be a false cause (ADR-009 rule 2,
+                // caught in review). The error message is the evidence; the test-runner
+                // sentence is offered as the common case, not stated as the cause.
+                writeStderr(`Error: ${file} could not be loaded (${error instanceof Error ? error.message : String(error)}), ` +
+                    `so none of it could be diagnosed. If this file imports a test runner (vitest/jest), ` +
+                    `doctor cannot load it — run your test suite instead; the runtime writes the same ` +
+                    `diagnostics to stderr.\n`);
+            }
+            loadFailures.push({ file, error: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    // Orphan exclusion comments, AFTER the loop and over every rule at once
+    // (bug 0044). Not inside the loop and not inside `diagnose()`: the declared-id
+    // set is the union across rule files, so a per-file check would report a
+    // directive naming a rule declared in a sibling file as an orphan. That is a
+    // false positive on the commonest multi-file layout, and a diagnostic that
+    // cries wolf is one nobody runs.
+    //
+    // Reported as `dead-glob`'s sibling kind rather than a separate output
+    // section, so `--format json` consumers get it through the `findings` array
+    // they already parse.
+    // The scope is passed, so the advice can say what it checked. `doctor
+    // arch.rules.ts` — the single-file form `docs/cli.md` itself shows — sees a
+    // subset of a multi-file project's rules, and a directive naming a rule from
+    // another file would otherwise be reported as an orphan with "delete the
+    // comment" as its remedy. Deleting a working comment un-waives a real
+    // violation, which is the rule-2 failure this caveat exists to prevent.
+    for (const orphan of orphanExclusions(rules, { ruleFilesChecked: args.ruleFiles.length })) {
+        findings.push({
+            kind: 'orphan-exclusion',
+            rule: orphan.ruleId,
+            advice: orphan.advice,
+            // `sourceFile`, not `ruleFile`: that field is documented as "the rule file
+            // this rule was written in", and putting a *source* path there gave JSON
+            // consumers two different things under one name, by `kind`, undocumented.
+            sourceFile: orphan.file,
+            line: orphan.line,
+        });
+    }
+    // A load failure is a REPORT, and this command's contract is "exits
+    // non-zero when it reports anything". Review measured the mixed case —
+    // one broken file, one clean file, zero findings — printing the error and
+    // then exiting 0 with a clean bill of health: exactly the "exit 0 plus
+    // silence" this command exists to prevent, reintroduced by the catch that
+    // fixed the crash. Every exit path below folds the load failures in.
+    //
+    // And every exit path emits the JSON document when asked for it: a consumer
+    // parsing stdout used to get zero bytes on the commonest single-file failure,
+    // and `JSON.parse('')` throws — the exact consumer the exit-code fix was for.
+    const emitJson = (findings) => {
+        if (args.format === 'json') {
+            process.stdout.write(JSON.stringify({ findings, loadFailures }, null, 2) + '\n');
+        }
+    };
+    if (loadFailures.length > 0 && rules.length === 0) {
+        emitJson([]);
+        return 1;
+    }
+    // Nothing to diagnose is not the same as nothing wrong. The earlier guard
+    // checked `args.ruleFiles.length`, which is the wrong derivation: a file
+    // exporting `[]` reached this point and reported a clean bill of health.
+    if (rules.length === 0) {
+        writeStderr('Error: no rules found in the given files.\n');
+        emitJson([]);
+        return 1;
+    }
+    if (args.format === 'json') {
+        emitJson(findings);
+        return findings.length > 0 || loadFailures.length > 0 ? 1 : 0;
+    }
+    if (findings.length === 0) {
+        if (loadFailures.length > 0) {
+            writeStderr('No findings in the rules that loaded — but at least one file could not be ' +
+                'loaded (see above), so this is not a clean bill of health.\n');
+            return 1;
+        }
+        writeStderr('No rules that cannot enforce anything.\n');
+        return 0;
+    }
+    writeStderr(format(findings));
+    return 1;
+}
+/**
+ * Which kinds carry a glob, and therefore render with origin/position/fault.
+ *
+ * A `Record` over the union rather than a boolean expression, so that adding a
+ * kind fails `tsc` until someone decides how it renders. `project-empty` was
+ * added to `DiagnosticFinding['kind']` and this file kept compiling — the gap
+ * that made the choice implicit.
+ */
+const HAS_GLOB = {
+    'dead-glob': true,
+    'no-condition': false,
+    'project-unknown': false,
+    'project-empty': false,
+    // No glob: the fault is the family's own filters emptying the set, so there
+    // is no glob text to point at (plan 0096).
+    'zero-subjects': false,
+    // No glob: the fault is the family's own adequacy predicate, not a
+    // selector — the corpus was found and examined, it just cannot ever
+    // produce a finding as configured (plan 0102).
+    inert: false,
+    // No glob: the subject is a comment in a source file, and the identity is the
+    // rule id it names plus where it sits. That is why this kind carries `line`.
+    'orphan-exclusion': false,
+    // No glob: the fault is specific CURRENT violations not covered by the
+    // rule's own `accepted` list, not a selector — the corpus was found and
+    // examined, and some of what it found is not what was accepted (plan 0090).
+    'deferred-warning': false,
+};
+function format(findings) {
+    const lines = [''];
+    for (const finding of findings) {
+        // The rule file first: with two identical vacuous rules in two files, the
+        // rule's own description is the same sentence twice and says nothing about
+        // which to open.
+        // An orphan exclusion is located by its SOURCE file and line, not by a rule
+        // file — the subject is a comment. The changelog claimed this printed "the
+        // file and line" and the terminal format printed neither, so two stale
+        // directives in one file rendered as two identical headers.
+        if (finding.sourceFile !== undefined) {
+            const at = finding.line === undefined ? '' : `:${String(finding.line)}`;
+            lines.push(`  ${finding.sourceFile}${at}`);
+            lines.push(`    ${finding.rule}`);
+        }
+        else {
+            lines.push(finding.ruleFile === undefined ? `  ${finding.rule}` : `  ${finding.ruleFile}`);
+            if (finding.ruleFile !== undefined)
+                lines.push(`    ${finding.rule}`);
+        }
+        if (HAS_GLOB[finding.kind]) {
+            lines.push(`    ${finding.origin ?? finding.glob ?? '(unknown)'}  [${finding.position ?? 'unknown'}]`, `    ${finding.fault ?? 'unknown'}: ${finding.advice}`);
+        }
+        else {
+            // `no-condition`, `project-unknown` and `project-empty` have no glob, no
+            // position and no fault. Rendering them through the dead-glob shape
+            // printed `(unknown) [unknown]` / `unknown: …`, which reads like a bug in
+            // the tool rather than a finding about the rule.
+            //
+            // `HAS_GLOB` below is what makes adding a fifth kind a COMPILE error
+            // rather than a silent fall into this branch. `project-empty` was added
+            // to the union and compiled without anyone choosing a rendering for it —
+            // an if/else cannot ask the question, and `Record<K, …>` can. Same device
+            // as `FAULT_ADVICE` and `ON_DISK_ADVICE` in `glob-diagnosis.ts`.
+            lines.push(`    ${finding.kind}: ${finding.advice}`);
+        }
+        lines.push('');
+    }
+    // Deliberately no total. A count is the snapshot ADR-009 rule 4 bars, and it
+    // is the number people ratchet against instead of fixing the findings.
+    return lines.join('\n');
+}
+//# sourceMappingURL=doctor.js.map

package/dist/cli/commands/doctor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../../../src/cli/commands/doctor.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAA;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAA;AAOlE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,IAAgB;IAC9C,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChC,WAAW,CAAC,+EAA+E,CAAC,CAAA;QAC5F,OAAO,CAAC,CAAA;IACV,CAAC;IAED,4EAA4E;IAC5E,8EAA8E;IAC9E,uEAAuE;IACvE,MAAM,QAAQ,GAAwB,EAAE,CAAA;IACxC,MAAM,KAAK,GAAsB,EAAE,CAAA;IACnC,8EAA8E;IAC9E,4EAA4E;IAC5E,iCAAiC;IACjC,MAAM,YAAY,GAAsC,EAAE,CAAA;IAC1D,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;QAClC,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,CAAC,IAAI,CAAC,CAAC,CAAA;YAC1C,KAAK,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,CAAA;YACrB,QAAQ,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAA;QAC3E,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,sEAAsE;YACtE,uEAAuE;YACvE,mEAAmE;YACnE,sEAAsE;YACtE,mEAAmE;YACnE,qEAAqE;YACrE,uEAAuE;YACvE,gEAAgE;YAChE,qEAAqE;YACrE,wEAAwE;YACxE,wCAAwC;YACxC,EAAE;YACF,uEAAuE;YACvE,sEAAsE;YACtE,sEAAsE;YACtE,kDAAkD;YAClD,IAAI,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC3B,WAAW,CACT,UAAU,IAAI,kEAAkE;oBAC9E,uFAAuF,CAC1F,CAAA;YACH,CAAC;iBAAM,CAAC;gBACN,sEAAsE;gBACtE,uEAAuE;gBACvE,uEAAuE;gBACvE,wEAAwE;gBACxE,mEAAmE;gBACnE,WAAW,CACT,UAAU,IAAI,yBAAyB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK;oBAChG,sFAAsF;oBACtF,mFAAmF;oBACnF,0BAA0B,CAC7B,CAAA;YACH,CAAC;YACD,YAAY,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;QAC5F,CAAC;IACH,CAAC;IAED,wEAAwE;IACxE,+EAA+E;IAC/E,yEAAyE;IACzE,6EAA6E;IAC7E,2EAA2E;IAC3E,iCAAiC;IACjC,EAAE;IACF,uEAAuE;IACvE,4EAA4E;IAC5E,sBAAsB;IACtB,sEAAsE;IACtE,4EAA4E;IAC5E,6EAA6E;IAC7E,yEAAyE;IACzE,sEAAsE;IACtE,wEAAwE;IACxE,KAAK,MAAM,MAAM,IAAI,gBAAgB,CAAC,KAAK,EAAE,EAAE,gBAAgB,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC;QAC1F,QAAQ,CAAC,IAAI,CAAC;YACZ,IAAI,EAAE,kBAAkB;YACxB,IAAI,EAAE,MAAM,CAAC,MAAM;YACnB,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,2EAA2E;YAC3E,yEAAyE;YACzE,0EAA0E;YAC1E,UAAU,EAAE,MAAM,CAAC,IAAI;YACvB,IAAI,EAAE,MAAM,CAAC,IAAI;SAClB,CAAC,CAAA;IACJ,CAAC;IAED,oEAAoE;IACpE,uEAAuE;IACvE,0EAA0E;IAC1E,uEAAuE;IACvE,0EAA0E;IAC1E,qEAAqE;IACrE,EAAE;IACF,4EAA4E;IAC5E,8EAA8E;IAC9E,8EAA8E;IAC9E,MAAM,QAAQ,GAAG,CAAC,QAA6B,EAAQ,EAAE;QACvD,IAAI,IAAI,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;YAC3B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,QAAQ,EAAE,YAAY,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAA;QAClF,CAAC;IACH,CAAC,CAAA;IAED,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClD,QAAQ,CAAC,EAAE,CAAC,CAAA;QACZ,OAAO,CAAC,CAAA;IACV,CAAC;IAED,0EAA0E;IAC1E,yEAAyE;IACzE,yEAAyE;IACzE,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,WAAW,CAAC,6CAA6C,CAAC,CAAA;QAC1D,QAAQ,CAAC,EAAE,CAAC,CAAA;QACZ,OAAO,CAAC,CAAA;IACV,CAAC;IAED,IAAI,IAAI,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;QAC3B,QAAQ,CAAC,QAAQ,CAAC,CAAA;QAClB,OAAO,QAAQ,CAAC,MAAM,GAAG,CAAC,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IAC/D,CAAC;IAED,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC5B,WAAW,CACT,4EAA4E;gBAC1E,8DAA8D,CACjE,CAAA;YACD,OAAO,CAAC,CAAA;QACV,CAAC;QACD,WAAW,CAAC,0CAA0C,CAAC,CAAA;QACvD,OAAO,CAAC,CAAA;IACV,CAAC;IAED,WAAW,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAA;IAC7B,OAAO,CAAC,CAAA;AACV,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,QAAQ,GAAyD;IACrE,WAAW,EAAE,IAAI;IACjB,cAAc,EAAE,KAAK;IACrB,iBAAiB,EAAE,KAAK;IACxB,eAAe,EAAE,KAAK;IACtB,4EAA4E;IAC5E,2CAA2C;IAC3C,eAAe,EAAE,KAAK;IACtB,mEAAmE;IACnE,oEAAoE;IACpE,+CAA+C;IAC/C,KAAK,EAAE,KAAK;IACZ,8EAA8E;IAC9E,6EAA6E;IAC7E,kBAAkB,EAAE,KAAK;IACzB,uEAAuE;IACvE,wEAAwE;IACxE,4EAA4E;IAC5E,kBAAkB,EAAE,KAAK;CAC1B,CAAA;AAED,SAAS,MAAM,CAAC,QAAsC;IACpD,MAAM,KAAK,GAAa,CAAC,EAAE,CAAC,CAAA;IAC5B,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,0EAA0E;QAC1E,2EAA2E;QAC3E,iBAAiB;QACjB,4EAA4E;QAC5E,2EAA2E;QAC3E,uEAAuE;QACvE,4DAA4D;QAC5D,IAAI,OAAO,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;YACrC,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAA;YACvE,KAAK,CAAC,IAAI,CAAC,KAAK,OAAO,CAAC,UAAU,GAAG,EAAE,EAAE,CAAC,CAAA;YAC1C,KAAK,CAAC,IAAI,CAAC,OAAO,OAAO,CAAC,IAAI,EAAE,CAAC,CAAA;QACnC,CAAC;aAAM,CAAC;YACN,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAA;YAC1F,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS;gBAAE,KAAK,CAAC,IAAI,CAAC,OAAO,OAAO,CAAC,IAAI,EAAE,CAAC,CAAA;QACvE,CAAC;QACD,IAAI,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;YAC3B,KAAK,CAAC,IAAI,CACR,OAAO,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,IAAI,IAAI,WAAW,MAAM,OAAO,CAAC,QAAQ,IAAI,SAAS,GAAG,EAC1F,OAAO,OAAO,CAAC,KAAK,IAAI,SAAS,KAAK,OAAO,CAAC,MAAM,EAAE,CACvD,CAAA;QACH,CAAC;aAAM,CAAC;YACN,yEAAyE;YACzE,oEAAoE;YACpE,0EAA0E;YAC1E,iDAAiD;YACjD,EAAE;YACF,qEAAqE;YACrE,wEAAwE;YACxE,yEAAyE;YACzE,0EAA0E;YAC1E,iEAAiE;YACjE,KAAK,CAAC,IAAI,CAAC,OAAO,OAAO,CAAC,IAAI,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;QACtD,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IAChB,CAAC;IACD,6EAA6E;IAC7E,uEAAuE;IACvE,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACzB,CAAC"}

package/dist/cli/commands/explain.d.ts

@@ -1,4 +1,4 @@
-export interface ExplainArgs {
+interface ExplainArgs {
     ruleFiles: string[];
     markdown?: boolean;
     /** Explain output format: 'json' (default), 'markdown', or 'agent'. */
@@ -8,4 +8,5 @@ export interface ExplainArgs {
  * Dump all active rules as structured JSON or markdown.
  */
 export declare function runExplain(args: ExplainArgs): Promise<void>;
+export {};
 //# sourceMappingURL=explain.d.ts.map

package/dist/cli/commands/explain.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"explain.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/explain.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,EAAE,CAAA;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAgBD;;GAEG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBjE"}
+{"version":3,"file":"explain.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/explain.ts"],"names":[],"mappings":"AAIA,UAAU,WAAW;IACnB,SAAS,EAAE,MAAM,EAAE,CAAA;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED;;GAEG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBjE"}

package/dist/cli/commands/explain.js

@@ -1,11 +1,5 @@
+import { isDescribable } from '@nielspeter/eess/internal';
 import { loadRuleFiles } from '../load-rules.js';
-function isDescribable(value) {
-    return (value !== null &&
-        value !== undefined &&
-        typeof value === 'object' &&
-        'describeRule' in value &&
-        typeof value['describeRule'] === 'function');
-}
 /**
  * Dump all active rules as structured JSON or markdown.
  */
@@ -42,7 +36,7 @@ function outputAgent(descriptions) {
         'The following rules are enforced by CI. Violations will block your PR.',
         '',
         '**Verify before you continue:** after writing or changing code, run ' +
-            '`eess-ts check --format json`, read the `violations` array, and fix ' +
+            '`npx eess-ts check --format json`, read the `violations` array, and fix ' +
             'each one using its `suggestion`. Do this in your edit loop — do not wait for CI.',
         '',
     ];
@@ -62,10 +56,24 @@ function outputAgent(descriptions) {
     }
     for (const [group, rules] of groups) {
         lines.push(`### ${titleCase(group)}`, '');
+        // Deduplicated within the group. A preset generates one rule per configured
+        // folder — `strictBoundaries({ folders })` with six boundaries produces six
+        // `no-cross-boundary` rules carrying IDENTICAL metadata — so the same bullet
+        // printed six times. This output is meant to be committed into an agent's
+        // system prompt (`init` says so), where repetition is pure cost: it is
+        // tokens on every request and it reads as six different rules.
+        //
+        // The bullet TEXT is the key, not the rule id: two rules can share an id and
+        // differ in imperative, and it is the line that would repeat.
+        const seen = new Set();
         for (const d of rules) {
             // The imperative is the self-contained rule statement; `because`/`suggestion`
             // live in the check --format json payload, so don't double them up here.
-            lines.push(`- ${d.imperative ?? (d.rule || 'Follow the architecture rule.')}`);
+            const bullet = d.imperative ?? (d.rule || 'Follow the architecture rule.');
+            if (seen.has(bullet))
+                continue;
+            seen.add(bullet);
+            lines.push(`- ${bullet}`);
         }
         lines.push('');
     }
@@ -73,7 +81,8 @@ function outputAgent(descriptions) {
     process.stdout.write(lines.join('\n') + '\n');
 }
 function titleCase(s) {
-    return s.length === 0 ? s : (s[0] ?? '').toUpperCase() + s.slice(1);
+    const [first] = s;
+    return first === undefined ? s : first.toUpperCase() + s.slice(1);
 }
 function outputJson(descriptions) {
     const output = {

package/dist/cli/commands/explain.js.map

@@ -1 +1 @@
-{"version":3,"file":"explain.js","sourceRoot":"","sources":["../../../src/cli/commands/explain.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"explain.js","sourceRoot":"","sources":["../../../src/cli/commands/explain.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AAEzD,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAShD;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAAiB;IAChD,MAAM,QAAQ,GAAG,MAAM,aAAa,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;IAEpD,MAAM,YAAY,GAAsB,EAAE,CAAA;IAC1C,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,IAAI,aAAa,CAAC,OAAO,CAAC,EAAE,CAAC;YAC3B,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,CAAC,CAAA;QAC3C,CAAC;IACH,CAAC;IAED,IAAI,IAAI,CAAC,MAAM,KAAK,OAAO,EAAE,CAAC;QAC5B,WAAW,CAAC,YAAY,CAAC,CAAA;IAC3B,CAAC;SAAM,IAAI,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;QACvD,cAAc,CAAC,YAAY,CAAC,CAAA;IAC9B,CAAC;SAAM,CAAC;QACN,UAAU,CAAC,YAAY,CAAC,CAAA;IAC1B,CAAC;AACH,CAAC;AAED,MAAM,WAAW,GAAG,wBAAwB,CAAA;AAC5C,MAAM,SAAS,GAAG,sBAAsB,CAAA;AAExC;;;GAGG;AACH,SAAS,WAAW,CAAC,YAA+B;IAClD,MAAM,KAAK,GAAa;QACtB,WAAW;QACX,EAAE;QACF,mDAAmD;QACnD,EAAE;QACF,wEAAwE;QACxE,EAAE;QACF,sEAAsE;YACpE,0EAA0E;YAC1E,kFAAkF;QACpF,EAAE;KACH,CAAA;IAED,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC9B,KAAK,CAAC,IAAI,CAAC,mBAAmB,EAAE,EAAE,EAAE,SAAS,CAAC,CAAA;QAC9C,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,CAAA;QAC7C,OAAM;IACR,CAAC;IAED,4EAA4E;IAC5E,mDAAmD;IACnD,MAAM,MAAM,GAAG,IAAI,GAAG,EAA6B,CAAA;IACnD,KAAK,MAAM,CAAC,IAAI,YAAY,EAAE,CAAC;QAC7B,MAAM,GAAG,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;QAChE,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAA;QACnC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;QACb,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;IACxB,CAAC;IAED,KAAK,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,MAAM,EAAE,CAAC;QACpC,KAAK,CAAC,IAAI,CAAC,OAAO,SAAS,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,CAAA;QACzC,4EAA4E;QAC5E,4EAA4E;QAC5E,6EAA6E;QAC7E,0EAA0E;QAC1E,uEAAuE;QACvE,+DAA+D;QAC/D,EAAE;QACF,6EAA6E;QAC7E,8DAA8D;QAC9D,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAA;QAC9B,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;YACtB,8EAA8E;YAC9E,yEAAyE;YACzE,MAAM,MAAM,GAAG,CAAC,CAAC,UAAU,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,+BAA+B,CAAC,CAAA;YAC1E,IAAI,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC;gBAAE,SAAQ;YAC9B,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;YAChB,KAAK,CAAC,IAAI,CAAC,KAAK,MAAM,EAAE,CAAC,CAAA;QAC3B,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IAChB,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;IACrB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,CAAA;AAC/C,CAAC;AAED,SAAS,SAAS,CAAC,CAAS;IAC1B,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IACjB,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;AACnE,CAAC;AAED,SAAS,UAAU,CAAC,YAA+B;IACjD,MAAM,MAAM,GAAG;QACb,KAAK,EAAE,YAAY;QACnB,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACtC,CAAA;IACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAA;AAC9D,CAAC;AAED,SAAS,cAAc,CAAC,YAA+B;IACrD,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC9B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,mBAAmB,CAAC,CAAA;QACzC,OAAM;IACR,CAAC;IAED,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,wCAAwC,CAAC,CAAA;IAC9D,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,wCAAwC,CAAC,CAAA;IAC9D,KAAK,MAAM,CAAC,IAAI,YAAY,EAAE,CAAC;QAC7B,MAAM,EAAE,GAAG,CAAC,CAAC,EAAE,IAAI,GAAG,CAAA;QACtB,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,IAAI,GAAG,CAAA;QAC1B,MAAM,OAAO,GAAG,CAAC,CAAC,OAAO,IAAI,GAAG,CAAA;QAChC,MAAM,UAAU,GAAG,CAAC,CAAC,UAAU,IAAI,GAAG,CAAA;QACtC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,MAAM,IAAI,MAAM,OAAO,MAAM,UAAU,MAAM,CAAC,CAAA;IAC5E,CAAC;AACH,CAAC"}

package/dist/cli/commands/init.d.ts

@@ -1,7 +1,11 @@
-export interface InitArgs {
+interface InitArgs {
     /** Directory to scaffold into. Defaults to `process.cwd()`. */
     cwd?: string;
-    /** Starter preset: `recommended` (default) | `agent-guardrails`. */
+    /**
+     * Starter preset. Floor: `recommended` (default) | `agent-guardrails`.
+     * Shape: `layered` | `strict-boundaries` | `data-layer` (scaffolded with
+     * fill-in folder globs, alongside the `recommended` floor).
+     */
     preset?: string;
     /** tsconfig path written into the generated files. Default `tsconfig.json`. */
     tsconfig?: string;
@@ -17,7 +21,9 @@ export interface InitArgs {
  * (0 success, 1 on a recoverable error — bad `--preset`, missing tsconfig, a
  * file conflict without `--force`, or a write failure). All reads, parses, and
  * conflict checks run before any file is written, so a validation failure never
- * leaves a partial scaffold; a raw I/O failure mid-write is caught and reported.
+ * leaves a partial scaffold; a raw I/O failure mid-write is caught and reported
+ * (writes are ordered, not transactional).
  */
 export declare function runInit(args: InitArgs): number;
+export {};
 //# sourceMappingURL=init.d.ts.map

package/dist/cli/commands/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/init.ts"],"names":[],"mappings":"AAkBA,MAAM,WAAW,QAAQ;IACvB,+DAA+D;IAC/D,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,oDAAoD;IACpD,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,qCAAqC;IACrC,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,wEAAwE;IACxE,UAAU,CAAC,EAAE,OAAO,CAAA;CACrB;AAUD;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAyE9C"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/init.ts"],"names":[],"mappings":"AAgBA,UAAU,QAAQ;IAChB,+DAA+D;IAC/D,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,oDAAoD;IACpD,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,qCAAqC;IACrC,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,wEAAwE;IACxE,UAAU,CAAC,EAAE,OAAO,CAAA;CACrB;AAUD;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAyE9C"}