@thymian/plugin-spectral 0.2.0-canary.20260810-95e9b0c

package/dist/convert.d.ts

@@ -0,0 +1,19 @@
+import type { LintExecution, Logger, RuleDescriptor, ThymianFormat } from '@thymian/core';
+import type { SpectralResult } from './spectral-types.js';
+export interface ConvertedResults {
+    executions: LintExecution[];
+    rules: RuleDescriptor[];
+}
+/**
+ * Maps Spectral results to failed lint executions plus one RuleDescriptor per
+ * distinct code. Every Spectral result is a problem, so every execution is
+ * `failed` with the finding's own severity on the status (per-finding
+ * fidelity regardless of rule-level severity resolution); the descriptor
+ * carries the highest severity seen for its code and links back to Spectral's
+ * docs via `documentationUrl` when present.
+ */
+export declare function convertResults(results: SpectralResult[], options: {
+    logger: Logger;
+    format?: ThymianFormat;
+}): ConvertedResults;
+//# sourceMappingURL=convert.d.ts.map

package/dist/convert.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"convert.d.ts","sourceRoot":"","sources":["../src/convert.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,MAAM,EACN,cAAc,EAEd,aAAa,EACd,MAAM,eAAe,CAAC;AAGvB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AA+B1D,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,aAAa,EAAE,CAAC;IAC5B,KAAK,EAAE,cAAc,EAAE,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,cAAc,EAAE,EACzB,OAAO,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,aAAa,CAAA;CAAE,GAClD,gBAAgB,CAqClB"}

package/dist/convert.js

@@ -0,0 +1,67 @@
+import { mapLocation } from './map-location.js';
+/** DiagnosticSeverity → Thymian severity; exact 1:1 for 0/1/2/3. */
+const SEVERITY_BY_NUMBER = {
+    0: 'error',
+    1: 'warn',
+    2: 'info',
+    3: 'hint',
+};
+/** Higher number = more severe, for RuleDescriptor severity aggregation. */
+const SEVERITY_RANK = {
+    hint: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+function mapSeverity(severity, logger) {
+    const mapped = SEVERITY_BY_NUMBER[severity];
+    if (mapped === undefined) {
+        logger.warn(`Unknown Spectral severity ${severity.toString()} — converting conservatively as 'error'.`);
+        return 'error';
+    }
+    return mapped;
+}
+/**
+ * Maps Spectral results to failed lint executions plus one RuleDescriptor per
+ * distinct code. Every Spectral result is a problem, so every execution is
+ * `failed` with the finding's own severity on the status (per-finding
+ * fidelity regardless of rule-level severity resolution); the descriptor
+ * carries the highest severity seen for its code and links back to Spectral's
+ * docs via `documentationUrl` when present.
+ */
+export function convertResults(results, options) {
+    const executions = [];
+    const rulesById = new Map();
+    for (const result of results) {
+        const ruleId = `spectral/${String(result.code)}`;
+        const severity = mapSeverity(result.severity, options.logger);
+        executions.push({
+            kind: 'lint',
+            ruleId,
+            status: { kind: 'failed', reason: result.message, severity },
+            location: mapLocation(result, options.format),
+            findings: [],
+        });
+        const existing = rulesById.get(ruleId);
+        if (!existing) {
+            rulesById.set(ruleId, {
+                id: ruleId,
+                severity,
+                summary: { text: result.message },
+                ...(result.documentationUrl
+                    ? { helpUri: result.documentationUrl }
+                    : {}),
+            });
+        }
+        else {
+            if (SEVERITY_RANK[severity] > SEVERITY_RANK[existing.severity]) {
+                existing.severity = severity;
+            }
+            if (!existing.helpUri && result.documentationUrl) {
+                existing.helpUri = result.documentationUrl;
+            }
+        }
+    }
+    return { executions, rules: [...rulesById.values()] };
+}
+//# sourceMappingURL=convert.js.map

package/dist/convert.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"convert.js","sourceRoot":"","sources":["../src/convert.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGhD,oEAAoE;AACpE,MAAM,kBAAkB,GAA6B;IACnD,CAAC,EAAE,OAAO;IACV,CAAC,EAAE,MAAM;IACT,CAAC,EAAE,MAAM;IACT,CAAC,EAAE,MAAM;CACV,CAAC;AAEF,4EAA4E;AAC5E,MAAM,aAAa,GAA6B;IAC9C,IAAI,EAAE,CAAC;IACP,IAAI,EAAE,CAAC;IACP,IAAI,EAAE,CAAC;IACP,KAAK,EAAE,CAAC;CACT,CAAC;AAEF,SAAS,WAAW,CAAC,QAAgB,EAAE,MAAc;IACnD,MAAM,MAAM,GAAG,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IAE5C,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,MAAM,CAAC,IAAI,CACT,6BAA6B,QAAQ,CAAC,QAAQ,EAAE,0CAA0C,CAC3F,CAAC;QACF,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAOD;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAC5B,OAAyB,EACzB,OAAmD;IAEnD,MAAM,UAAU,GAAoB,EAAE,CAAC;IACvC,MAAM,SAAS,GAAG,IAAI,GAAG,EAA0B,CAAC;IAEpD,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,MAAM,MAAM,GAAG,YAAY,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;QACjD,MAAM,QAAQ,GAAG,WAAW,CAAC,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;QAE9D,UAAU,CAAC,IAAI,CAAC;YACd,IAAI,EAAE,MAAM;YACZ,MAAM;YACN,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,OAAO,EAAE,QAAQ,EAAE;YAC5D,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC;YAC7C,QAAQ,EAAE,EAAE;SACb,CAAC,CAAC;QAEH,MAAM,QAAQ,GAAG,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACvC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,SAAS,CAAC,GAAG,CAAC,MAAM,EAAE;gBACpB,EAAE,EAAE,MAAM;gBACV,QAAQ;gBACR,OAAO,EAAE,EAAE,IAAI,EAAE,MAAM,CAAC,OAAO,EAAE;gBACjC,GAAG,CAAC,MAAM,CAAC,gBAAgB;oBACzB,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,gBAAgB,EAAE;oBACtC,CAAC,CAAC,EAAE,CAAC;aACR,CAAC,CAAC;QACL,CAAC;aAAM,CAAC;YACN,IAAI,aAAa,CAAC,QAAQ,CAAC,GAAG,aAAa,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAC/D,QAAQ,CAAC,QAAQ,GAAG,QAAQ,CAAC;YAC/B,CAAC;YACD,IAAI,CAAC,QAAQ,CAAC,OAAO,IAAI,MAAM,CAAC,gBAAgB,EAAE,CAAC;gBACjD,QAAQ,CAAC,OAAO,GAAG,MAAM,CAAC,gBAAgB,CAAC;YAC7C,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC,GAAG,SAAS,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC;AACxD,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+import type { ThymianPlugin } from '@thymian/core';
+export type { SpectralResult } from './spectral-types.js';
+/**
+ * `@thymian/plugin-spectral` converts pre-generated Spectral JSON output
+ * (`spectral lint -f json`) into canonical Thymian lint runs. It never
+ * executes Spectral — the input is the report file. See
+ * {@link SpectralResult} for the supported input format.
+ *
+ * The plugin extends `thymian report convert` purely by listening on the
+ * core-owned `core.report.convert` collect action (ADR-0016/0017): it claims
+ * `spectral`-typed report inputs and replies one lint `ToolRun` per claimed
+ * input, tagged with that input's identity. The converted report kind is
+ * always `lint`.
+ */
+export declare function createSpectralPlugin(pluginName?: string): ThymianPlugin;
+export declare const spectralPlugin: ThymianPlugin;
+export default spectralPlugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAwB,aAAa,EAAE,MAAM,eAAe,CAAC;AAMzE,YAAY,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,SAA6B,GACtC,aAAa,CAgEf;AAED,eAAO,MAAM,cAAc,eAAyB,CAAC;AAErD,eAAe,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,68 @@
+import { createToolRun, ThymianFormat } from '@thymian/core';
+import { convertResults } from './convert.js';
+import { loadSpectralReport } from './load-spectral-report.js';
+/**
+ * `@thymian/plugin-spectral` converts pre-generated Spectral JSON output
+ * (`spectral lint -f json`) into canonical Thymian lint runs. It never
+ * executes Spectral — the input is the report file. See
+ * {@link SpectralResult} for the supported input format.
+ *
+ * The plugin extends `thymian report convert` purely by listening on the
+ * core-owned `core.report.convert` collect action (ADR-0016/0017): it claims
+ * `spectral`-typed report inputs and replies one lint `ToolRun` per claimed
+ * input, tagged with that input's identity. The converted report kind is
+ * always `lint`.
+ */
+export function createSpectralPlugin(pluginName = '@thymian/plugin-spectral') {
+    return {
+        name: pluginName,
+        version: '0.x',
+        actions: {
+            listensOn: ['core.report.convert'],
+        },
+        async plugin(emitter, logger, options) {
+            emitter.onAction('core.report.convert', async (input, ctx) => {
+                const spectralInputs = input.inputs.filter((reportInput) => reportInput.type === 'spectral');
+                // Always reply, even with nothing claimed — the collect strategy
+                // waits for every registered listener (14.1 listener contract).
+                if (spectralInputs.length === 0) {
+                    logger.info('No spectral report inputs found, nothing to convert.');
+                    ctx.reply([]);
+                    return;
+                }
+                const format = input.format
+                    ? ThymianFormat.import(input.format)
+                    : undefined;
+                const fragments = [];
+                for (const reportInput of spectralInputs) {
+                    const location = String(reportInput.location);
+                    const inputLabel = `${reportInput.type}:${location}`;
+                    logger.info(`Converting Spectral report: ${location}`);
+                    // Failures propagate as thrown ThymianBaseErrors — the intended
+                    // tool/runtime error semantics; never a silently dropped input.
+                    const results = await loadSpectralReport(location, inputLabel, options.cwd);
+                    const { executions, rules } = convertResults(results, {
+                        logger,
+                        format,
+                    });
+                    fragments.push({
+                        // Tag with the stringified input identity — core derives claim
+                        // coverage by exact type + String(location) match.
+                        input: { type: reportInput.type, location },
+                        run: createToolRun({
+                            tool: { name: pluginName },
+                            runType: 'lint',
+                            executions,
+                            rules: rules.length > 0 ? rules : undefined,
+                            thymianFormatVersion: input.format?.attributes.hash,
+                        }),
+                    });
+                }
+                ctx.reply(fragments);
+            });
+        },
+    };
+}
+export const spectralPlugin = createSpectralPlugin();
+export default spectralPlugin;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAE7D,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAI/D;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,oBAAoB,CAClC,UAAU,GAAG,0BAA0B;IAEvC,OAAO;QACL,IAAI,EAAE,UAAU;QAChB,OAAO,EAAE,KAAK;QACd,OAAO,EAAE;YACP,SAAS,EAAE,CAAC,qBAAqB,CAAC;SACnC;QACD,KAAK,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO;YACnC,OAAO,CAAC,QAAQ,CAAC,qBAAqB,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;gBAC3D,MAAM,cAAc,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,CACxC,CAAC,WAAW,EAAE,EAAE,CAAC,WAAW,CAAC,IAAI,KAAK,UAAU,CACjD,CAAC;gBAEF,iEAAiE;gBACjE,gEAAgE;gBAChE,IAAI,cAAc,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;oBAChC,MAAM,CAAC,IAAI,CAAC,sDAAsD,CAAC,CAAC;oBACpE,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;oBACd,OAAO;gBACT,CAAC;gBAED,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM;oBACzB,CAAC,CAAC,aAAa,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC;oBACpC,CAAC,CAAC,SAAS,CAAC;gBAEd,MAAM,SAAS,GAA2B,EAAE,CAAC;gBAE7C,KAAK,MAAM,WAAW,IAAI,cAAc,EAAE,CAAC;oBACzC,MAAM,QAAQ,GAAG,MAAM,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;oBAC9C,MAAM,UAAU,GAAG,GAAG,WAAW,CAAC,IAAI,IAAI,QAAQ,EAAE,CAAC;oBAErD,MAAM,CAAC,IAAI,CAAC,+BAA+B,QAAQ,EAAE,CAAC,CAAC;oBAEvD,gEAAgE;oBAChE,gEAAgE;oBAChE,MAAM,OAAO,GAAG,MAAM,kBAAkB,CACtC,QAAQ,EACR,UAAU,EACV,OAAO,CAAC,GAAG,CACZ,CAAC;oBAEF,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,cAAc,CAAC,OAAO,EAAE;wBACpD,MAAM;wBACN,MAAM;qBACP,CAAC,CAAC;oBAEH,SAAS,CAAC,IAAI,CAAC;wBACb,+DAA+D;wBAC/D,mDAAmD;wBACnD,KAAK,EAAE,EAAE,IAAI,EAAE,WAAW,CAAC,IAAI,EAAE,QAAQ,EAAE;wBAC3C,GAAG,EAAE,aAAa,CAAC;4BACjB,IAAI,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE;4BAC1B,OAAO,EAAE,MAAM;4BACf,UAAU;4BACV,KAAK,EAAE,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS;4BAC3C,oBAAoB,EAAE,KAAK,CAAC,MAAM,EAAE,UAAU,CAAC,IAAI;yBACpD,CAAC;qBACH,CAAC,CAAC;gBACL,CAAC;gBAED,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;YACvB,CAAC,CAAC,CAAC;QACL,CAAC;KACF,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,MAAM,cAAc,GAAG,oBAAoB,EAAE,CAAC;AAErD,eAAe,cAAc,CAAC"}

package/dist/load-spectral-report.d.ts

@@ -0,0 +1,15 @@
+import type { SpectralResult } from './spectral-types.js';
+/**
+ * Reads a single Spectral JSON report (`spectral lint -f json` output),
+ * validates its structure, and returns the parsed results.
+ *
+ * Unknown extra fields on entries are tolerated (forward-compatible).
+ *
+ * @param inputLabel the offending input's identity (`type:location`), used in
+ *   every error message so failures trace back to the CLI input (AC 5).
+ * @throws {ThymianBaseError} if the file is unreadable, not valid JSON, not a
+ *   result array, or an entry misses the required
+ *   `code`/`message`/`severity`/`path`/`range` shape.
+ */
+export declare function loadSpectralReport(location: string, inputLabel: string, cwd: string): Promise<SpectralResult[]>;
+//# sourceMappingURL=load-spectral-report.d.ts.map

package/dist/load-spectral-report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-spectral-report.d.ts","sourceRoot":"","sources":["../src/load-spectral-report.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AA8C1D;;;;;;;;;;;GAWG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,cAAc,EAAE,CAAC,CAsC3B"}

package/dist/load-spectral-report.js

@@ -0,0 +1,75 @@
+import { readFile } from 'node:fs/promises';
+import { isAbsolute, join } from 'node:path';
+import { ThymianBaseError } from '@thymian/core';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isNonNegativeInteger(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value >= 0;
+}
+function isPosition(value) {
+    return (isRecord(value) &&
+        isNonNegativeInteger(value['line']) &&
+        isNonNegativeInteger(value['character']));
+}
+function isStringWhenPresent(value) {
+    return value === undefined || typeof value === 'string';
+}
+// Validates the full declared SpectralResult contract — the `as
+// SpectralResult[]` cast below vouches for exactly what is checked here, so
+// every required field the mapping code dereferences must be covered.
+function isSpectralResult(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    const range = value['range'];
+    const code = value['code'];
+    return ((typeof code === 'string' || typeof code === 'number') &&
+        typeof value['message'] === 'string' &&
+        typeof value['severity'] === 'number' &&
+        Array.isArray(value['path']) &&
+        isRecord(range) &&
+        isPosition(range['start']) &&
+        isPosition(range['end']) &&
+        isStringWhenPresent(value['source']) &&
+        isStringWhenPresent(value['documentationUrl']));
+}
+/**
+ * Reads a single Spectral JSON report (`spectral lint -f json` output),
+ * validates its structure, and returns the parsed results.
+ *
+ * Unknown extra fields on entries are tolerated (forward-compatible).
+ *
+ * @param inputLabel the offending input's identity (`type:location`), used in
+ *   every error message so failures trace back to the CLI input (AC 5).
+ * @throws {ThymianBaseError} if the file is unreadable, not valid JSON, not a
+ *   result array, or an entry misses the required
+ *   `code`/`message`/`severity`/`path`/`range` shape.
+ */
+export async function loadSpectralReport(location, inputLabel, cwd) {
+    const filePath = isAbsolute(location) ? location : join(cwd, location);
+    let content;
+    try {
+        content = await readFile(filePath, 'utf-8');
+    }
+    catch (err) {
+        throw new ThymianBaseError(`Failed to read Spectral report "${inputLabel}" (resolved to ${filePath}).`, { cause: err instanceof Error ? err : undefined });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch (err) {
+        throw new ThymianBaseError(`Failed to parse Spectral report "${inputLabel}" as JSON.`, { cause: err instanceof Error ? err : undefined });
+    }
+    if (!Array.isArray(parsed)) {
+        throw new ThymianBaseError(`Unsupported Spectral report "${inputLabel}": expected the JSON array produced by \`spectral lint -f json\`.`);
+    }
+    for (const [index, entry] of parsed.entries()) {
+        if (!isSpectralResult(entry)) {
+            throw new ThymianBaseError(`Unsupported Spectral report "${inputLabel}": result ${index.toString()} does not match the \`spectral lint -f json\` result shape (code/message/severity/path/range).`);
+        }
+    }
+    return parsed;
+}
+//# sourceMappingURL=load-spectral-report.js.map

package/dist/load-spectral-report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-spectral-report.js","sourceRoot":"","sources":["../src/load-spectral-report.ts"],"names":[],"mappings":"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"}

package/dist/map-location.d.ts

@@ -0,0 +1,18 @@
+import type { Location, ThymianFormat } from '@thymian/core';
+import type { SpectralResult } from './spectral-types.js';
+/**
+ * Best-effort mapping of a Spectral finding onto the loaded format (AC 4):
+ *
+ * 1. With a format and a finding `source`: the graph node from the same source
+ *    file whose `sourceLocation.position` is nearest at-or-before the finding.
+ *    Positions are 1-based (openapi loc-mappers); Spectral ranges are 0-based,
+ *    so the finding line/column are shifted by +1 before comparing.
+ * 2. Otherwise, a `file` location from `source` + the finding range,
+ *    **1-based** line/column (0-based Spectral values shifted by +1).
+ * 3. Without a `source`, a `custom` location from the joined `path` segments.
+ *
+ * The fallback chain is the contract — full resolution is genuinely
+ * best-effort, never required.
+ */
+export declare function mapLocation(result: SpectralResult, format: ThymianFormat | undefined): Location;
+//# sourceMappingURL=map-location.d.ts.map

package/dist/map-location.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"map-location.d.ts","sourceRoot":"","sources":["../src/map-location.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAE7D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAuB1D;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,aAAa,GAAG,SAAS,GAChC,QAAQ,CAuDV"}

package/dist/map-location.js

@@ -0,0 +1,74 @@
+/**
+ * Does the finding's `source` refer to the node's source file? Spectral emits
+ * OS-native absolute paths while format nodes carry the path the spec was
+ * loaded from — backslashes are normalized so Windows sources match too, then
+ * paths match exactly or when one is a `/`-suffix of the other.
+ */
+function sourceMatches(source, nodePath) {
+    const normalizedSource = source.replaceAll('\\', '/');
+    const normalizedNodePath = nodePath.replaceAll('\\', '/');
+    if (!normalizedSource || !normalizedNodePath) {
+        return false;
+    }
+    return (normalizedSource === normalizedNodePath ||
+        normalizedSource.endsWith(`/${normalizedNodePath}`) ||
+        normalizedNodePath.endsWith(`/${normalizedSource}`));
+}
+/**
+ * Best-effort mapping of a Spectral finding onto the loaded format (AC 4):
+ *
+ * 1. With a format and a finding `source`: the graph node from the same source
+ *    file whose `sourceLocation.position` is nearest at-or-before the finding.
+ *    Positions are 1-based (openapi loc-mappers); Spectral ranges are 0-based,
+ *    so the finding line/column are shifted by +1 before comparing.
+ * 2. Otherwise, a `file` location from `source` + the finding range,
+ *    **1-based** line/column (0-based Spectral values shifted by +1).
+ * 3. Without a `source`, a `custom` location from the joined `path` segments.
+ *
+ * The fallback chain is the contract — full resolution is genuinely
+ * best-effort, never required.
+ */
+export function mapLocation(result, format) {
+    const line = result.range.start.line + 1;
+    const column = result.range.start.character + 1;
+    if (format && result.source) {
+        const source = result.source;
+        let bestId;
+        let bestLine = 0;
+        let bestColumn = 0;
+        format.graph.forEachNode((id, node) => {
+            const { sourceLocation } = node;
+            // URI-sourced nodes cannot match a Spectral file source — skip them.
+            if (!sourceLocation?.position ||
+                !('path' in sourceLocation) ||
+                !sourceMatches(source, sourceLocation.path)) {
+                return;
+            }
+            const { line: nodeLine, column: nodeColumn } = sourceLocation.position;
+            const atOrBefore = nodeLine < line || (nodeLine === line && nodeColumn <= column);
+            const nearerThanBest = nodeLine > bestLine ||
+                (nodeLine === bestLine && nodeColumn > bestColumn);
+            if (atOrBefore && (bestId === undefined || nearerThanBest)) {
+                bestId = id;
+                bestLine = nodeLine;
+                bestColumn = nodeColumn;
+            }
+        });
+        if (bestId !== undefined) {
+            return {
+                type: 'thymianFormat',
+                elementType: 'node',
+                elementId: bestId,
+                pointer: '',
+            };
+        }
+    }
+    if (result.source) {
+        return { type: 'file', path: result.source, line, column };
+    }
+    return {
+        type: 'custom',
+        value: result.path.length > 0 ? result.path.join('.') : 'unknown',
+    };
+}
+//# sourceMappingURL=map-location.js.map

package/dist/map-location.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"map-location.js","sourceRoot":"","sources":["../src/map-location.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,SAAS,aAAa,CAAC,MAAc,EAAE,QAAgB;IACrD,MAAM,gBAAgB,GAAG,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACtD,MAAM,kBAAkB,GAAG,QAAQ,CAAC,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAE1D,IAAI,CAAC,gBAAgB,IAAI,CAAC,kBAAkB,EAAE,CAAC;QAC7C,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,CACL,gBAAgB,KAAK,kBAAkB;QACvC,gBAAgB,CAAC,QAAQ,CAAC,IAAI,kBAAkB,EAAE,CAAC;QACnD,kBAAkB,CAAC,QAAQ,CAAC,IAAI,gBAAgB,EAAE,CAAC,CACpD,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,WAAW,CACzB,MAAsB,EACtB,MAAiC;IAEjC,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,CAAC;IACzC,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,SAAS,GAAG,CAAC,CAAC;IAEhD,IAAI,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;QAC5B,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;QAC7B,IAAI,MAA0B,CAAC;QAC/B,IAAI,QAAQ,GAAG,CAAC,CAAC;QACjB,IAAI,UAAU,GAAG,CAAC,CAAC;QAEnB,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,EAAE;YACpC,MAAM,EAAE,cAAc,EAAE,GAAG,IAAI,CAAC;YAEhC,qEAAqE;YACrE,IACE,CAAC,cAAc,EAAE,QAAQ;gBACzB,CAAC,CAAC,MAAM,IAAI,cAAc,CAAC;gBAC3B,CAAC,aAAa,CAAC,MAAM,EAAE,cAAc,CAAC,IAAI,CAAC,EAC3C,CAAC;gBACD,OAAO;YACT,CAAC;YAED,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,cAAc,CAAC,QAAQ,CAAC;YAEvE,MAAM,UAAU,GACd,QAAQ,GAAG,IAAI,IAAI,CAAC,QAAQ,KAAK,IAAI,IAAI,UAAU,IAAI,MAAM,CAAC,CAAC;YACjE,MAAM,cAAc,GAClB,QAAQ,GAAG,QAAQ;gBACnB,CAAC,QAAQ,KAAK,QAAQ,IAAI,UAAU,GAAG,UAAU,CAAC,CAAC;YAErD,IAAI,UAAU,IAAI,CAAC,MAAM,KAAK,SAAS,IAAI,cAAc,CAAC,EAAE,CAAC;gBAC3D,MAAM,GAAG,EAAE,CAAC;gBACZ,QAAQ,GAAG,QAAQ,CAAC;gBACpB,UAAU,GAAG,UAAU,CAAC;YAC1B,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,OAAO;gBACL,IAAI,EAAE,eAAe;gBACrB,WAAW,EAAE,MAAM;gBACnB,SAAS,EAAE,MAAM;gBACjB,OAAO,EAAE,EAAE;aACZ,CAAC;QACJ,CAAC;IACH,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;QAClB,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAC7D,CAAC;IAED,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS;KAClE,CAAC;AACJ,CAAC"}

package/dist/spectral-types.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The supported Spectral input: the JSON array produced by
+ * `spectral lint -f json` (`@stoplight/spectral-cli`).
+ *
+ * Field set as emitted by Spectral's `json` formatter: `code`, `path`,
+ * `message`, `severity`, `range`, `source`, plus `documentationUrl` only when
+ * the rule declares one. Verified against real Spectral 6 output.
+ *
+ * - `range` positions are **0-based** (lines and characters).
+ * - `severity` numbers are DiagnosticSeverity: 0=error, 1=warning,
+ *   2=information, 3=hint.
+ * - Unknown extra fields are tolerated (forward-compatible); unknown severity
+ *   numbers convert conservatively to `error` with a warning — findings are
+ *   never dropped.
+ */
+export interface SpectralResult {
+    /** Rule identifier; Spectral allows numeric codes — stringified on mapping. */
+    code: string | number;
+    message: string;
+    /** DiagnosticSeverity: 0=error, 1=warning, 2=information, 3=hint. */
+    severity: number;
+    /** JSON path segments of the offending document location. */
+    path: (string | number)[];
+    /** 0-based document range of the finding. */
+    range: {
+        start: {
+            line: number;
+            character: number;
+        };
+        end: {
+            line: number;
+            character: number;
+        };
+    };
+    /** Source file the finding refers to, when Spectral knows it. */
+    source?: string;
+    /** Rule documentation link, present only when the rule declares one. */
+    documentationUrl?: string;
+}
+//# sourceMappingURL=spectral-types.d.ts.map

package/dist/spectral-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spectral-types.d.ts","sourceRoot":"","sources":["../src/spectral-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,cAAc;IAC7B,+EAA+E;IAC/E,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,QAAQ,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,IAAI,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;IAC1B,6CAA6C;IAC7C,KAAK,EAAE;QACL,KAAK,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,SAAS,EAAE,MAAM,CAAA;SAAE,CAAC;QAC3C,GAAG,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,SAAS,EAAE,MAAM,CAAA;SAAE,CAAC;KAC1C,CAAC;IACF,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B"}

package/dist/spectral-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=spectral-types.js.map

package/dist/spectral-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spectral-types.js","sourceRoot":"","sources":["../src/spectral-types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@thymian/plugin-spectral",
+  "version": "0.2.0-canary.20260810-95e9b0c",
+  "description": "Thymian plugin that converts pre-generated Spectral JSON output into canonical Thymian lint reports",
+  "license": "AGPL-3.0-only",
+  "bugs": {
+    "url": "https://github.com/thymianofficial/thymian/issues"
+  },
+  "homepage": "https://thymian.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/thymianofficial/thymian.git",
+    "directory": "packages/plugin-spectral"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "thymian",
+    "spectral",
+    "report-converter",
+    "lint",
+    "api-conformance"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!**/*.tsbuildinfo"
+  ],
+  "dependencies": {
+    "@thymian/core": "0.2.0-canary.20260810-95e9b0c",
+    "tslib": "^2.3.0"
+  },
+  "devDependencies": {
+    "@thymian/core-testing": "0.2.0-canary.20260810-95e9b0c"
+  }
+}