@agentxm/workspace-lint 0.28.4-bootstrap.0

package/dist/src/cli.d.ts

@@ -0,0 +1,239 @@
+/**
+ * Lint runner — the reusable core of `axm lint`.
+ *
+ * The `axm lint` CLI command file is a thin surface over flag parsing and
+ * rendering; the logic that evaluates rule catalogs, renders findings, and
+ * detects publish-gate drift lives in this module.
+ *
+ * Lint engine entry points:
+ *
+ * - {@link evaluateAllCatalogs}         — concurrent evaluation of the three
+ *   v1 rule catalogs against pre-built contexts.
+ * - {@link summarizeEvaluations}        — group, count, and derive the exit
+ *   category from raw `Evaluated<*>` lists.
+ * - {@link detectPublishGateDrift}      — compute whether the configured
+ *   `LintConfig` weakens any `skill/*` / `pack/*` platform-default-`error`
+ *   rule (task 5.7).
+ * - {@link renderFindingsText}          — finding-first human renderer (task
+ *   5.6).
+ * - {@link toLintJsonDocument}          — `--json` document shape (task 5.6).
+ * - {@link resolveLintExitCategory}     — exit-code contract evaluator (task
+ *   5.9).
+ *
+ * Lint-intent → canonical `Operation` adapter composition happens in the CLI
+ * handler (`packages/cli/src/root/lint/handler.ts`), which re-resolves each
+ * intent's `source` via the `resolveConfigured*` helpers and hands the
+ * resulting canonical Operation to the per-extension plan-step builder. The
+ * runner here stays accessor-free.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as Effect from "effect/Effect";
+import type { LintConfig } from "@agentxm/registry-protocol/unstable/lint/config";
+import { platformCanonicalLintConfig } from "@agentxm/registry-protocol/unstable/lint/config";
+import type { Evaluated } from "@agentxm/registry-protocol/unstable/lint/evaluate";
+import type { LintInput, LintJsonDocument } from "./json-schema.js";
+import type { LintFinding, Severity } from "@agentxm/registry-protocol/unstable/lint/rule";
+import type { AxmSkillCompatibility } from "@agentxm/extension-workspace";
+import { type CatalogContext, type CatalogGroup, type CatalogRuleContexts, type LintView } from "./catalog-contexts.js";
+/**
+ * A single finding annotated with the context that produced it.
+ *
+ * `displayRoot` carries the context's rendering root; `path` is the
+ * pre-composed display path for the finding so consumers (text / JSON /
+ * summary logs) don't re-derive it.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface RenderedFinding {
+    readonly group: CatalogGroup;
+    readonly ruleDescription: string;
+    readonly displayRoot: string;
+    readonly path: string;
+    readonly finding: LintFinding;
+}
+/**
+ * Per-group evaluation result, one entry per catalog. The raw `Evaluated<*>`
+ * list is retained so downstream consumers can render and emit JSON without
+ * re-running rules.
+ *
+ * Every group is required: a catalog that produced no findings still reports
+ * an empty list, so a missing group means a runner bug rather than "nothing to
+ * say".
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export type GroupEvaluations = {
+    readonly [K in CatalogGroup]: ReadonlyArray<Evaluated<CatalogContext<K>>>;
+};
+/**
+ * Aggregate counts across all emitted findings.
+ *
+ * `total` === `errors + warnings + infos` — info findings participate in
+ * rendering and in the JSON envelope, but never influence exit code.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface FindingCounts {
+    readonly total: number;
+    readonly errors: number;
+    readonly warnings: number;
+    readonly infos: number;
+}
+/**
+ * Possible exit-code categories for `axm lint`.
+ *
+ * - `"clean"` — zero findings, or only info-severity findings; zero exit.
+ * - `"warnings"` — at least one warning, no errors; non-zero only when
+ *   `--strict` is set (see {@link resolveLintExitCategory}).
+ * - `"errors"` — at least one error; non-zero exit regardless of flags.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export type LintExitCategory = "clean" | "warnings" | "errors";
+/**
+ * Evaluate every rule catalog against its contexts, concurrently.
+ *
+ * Catalogs run in parallel; findings stay in stable catalog order inside each
+ * group, and groups render in {@link CATALOG_GROUP_ORDER}.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const evaluateAllCatalogs: (args: {
+    readonly contexts: CatalogRuleContexts;
+    readonly config: LintConfig;
+    readonly view: LintView;
+}) => Effect.Effect<GroupEvaluations>;
+/**
+ * Flatten a {@link GroupEvaluations} record into a single `RenderedFinding[]`
+ * in stable group-then-catalog order.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const collectRenderedFindings: (evaluations: GroupEvaluations) => ReadonlyArray<RenderedFinding>;
+/**
+ * Count findings by severity across every group.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const countFindings: (findings: ReadonlyArray<RenderedFinding>) => FindingCounts;
+/**
+ * Aggregated summary — counts + derived exit category — computed from a
+ * {@link GroupEvaluations} triple.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface LintSummary {
+    readonly findings: ReadonlyArray<RenderedFinding>;
+    readonly counts: FindingCounts;
+    readonly exitCategory: LintExitCategory;
+    readonly driftBanner: ReadonlyArray<string>;
+}
+/**
+ * Derive a full {@link LintSummary} (findings, counts, exit category, drift
+ * banner rule ids) from raw evaluations + the configured severity overrides.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const summarizeEvaluations: (evaluations: GroupEvaluations, config: LintConfig) => LintSummary;
+/**
+ * Translate a {@link LintExitCategory} + `--strict` into the exit-code
+ * policy.
+ *
+ * | Category     | --strict=false | --strict=true |
+ * | ------------ | -------------- | ------------- |
+ * | `"clean"`    | `0`            | `0`           |
+ * | `"warnings"` | `0`            | non-zero      |
+ * | `"errors"`   | non-zero       | non-zero      |
+ *
+ * The return value is a discriminated enum; the CLI handler maps the `"fail"`
+ * branch to its platform exit-code primitive.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const resolveLintExitCategory: (args: {
+    readonly category: LintExitCategory;
+    readonly strict: boolean;
+}) => "success" | "fail";
+/**
+ * Identify every configured `lint.rules` entry that weakens a platform-canonical
+ * `error`-severity `skill/*` or `pack/*` rule.
+ *
+ * The publish gate runs the `skill/*` and `pack/*` catalogs against
+ * {@link platformCanonicalLintConfig}; any workspace override that lowers a
+ * rule in those namespaces from `error` to `off | info | warn` creates a
+ * publish-gate divergence the user should know about (they'll see `error`
+ * findings from the registry that don't appear locally).
+ *
+ * WorkspaceMutations-only rule weakenings (`workspace/*`) do NOT trigger the banner —
+ * those never reach publish.
+ *
+ * Returns the rule ids that trigger the banner, in catalog order, so the
+ * renderer can produce stable deterministic output.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const detectPublishGateDrift: (config: LintConfig) => ReadonlyArray<string>;
+/**
+ * Input for the human text renderer.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export type LintHumanReporter = "grouped" | "full" | "summary";
+export interface RenderFindingsArgs {
+    readonly summary: LintSummary;
+    readonly reporter?: LintHumanReporter;
+}
+export interface LintHumanDiagnostic {
+    readonly severity: Severity;
+    readonly ruleId: string;
+    readonly title: string;
+    readonly details: ReadonlyArray<string>;
+    readonly helps: ReadonlyArray<string>;
+    readonly fixable: boolean;
+    readonly paths: ReadonlyArray<string>;
+}
+export type LintHumanBlock = {
+    readonly kind: "overview";
+    readonly message: string;
+    readonly counts: FindingCounts;
+    readonly notes: ReadonlyArray<string>;
+} | {
+    readonly kind: "driftBanner";
+    readonly title: string;
+    readonly ruleIds: ReadonlyArray<string>;
+} | {
+    readonly kind: "section";
+    readonly title: string;
+    readonly note?: string;
+} | {
+    readonly kind: "diagnostic";
+    readonly diagnostic: LintHumanDiagnostic;
+} | {
+    readonly kind: "pathGroup";
+    readonly path: string;
+    readonly diagnostics: ReadonlyArray<LintHumanDiagnostic>;
+} | {
+    readonly kind: "blank";
+} | {
+    readonly kind: "empty";
+    readonly message: string;
+} | {
+    readonly kind: "footer";
+    readonly message: string;
+};
+export declare const toLintHumanBlocks: (args: RenderFindingsArgs) => ReadonlyArray<LintHumanBlock>;
+export declare const renderFindingsText: (args: RenderFindingsArgs) => ReadonlyArray<string>;
+/**
+ * Build the `--json` document from a {@link LintSummary}.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const toLintJsonDocument: (args: {
+    readonly summary: LintSummary;
+    readonly input: LintInput;
+    readonly axmSkillCompatibility?: AxmSkillCompatibility;
+}) => LintJsonDocument;
+export { platformCanonicalLintConfig };
+//# sourceMappingURL=cli.d.ts.map