@platformos/platformos-mcp-supervisor 0.0.2 → 0.2.0

package/dist/lint/lint-batch.spec.js

@@ -0,0 +1,503 @@
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { runBatchLint } from './lint-batch.js';
+/**
+ * Adapter integration: drives the real check-node `lintBuffers` against a temp
+ * project. Hermetic config (`extends: platformos-check:nothing` + one check) keeps
+ * the assertions deterministic and docset/network-free.
+ *
+ * This is the ONLY lint adapter — the orchestrator always works on a list, so a
+ * single file is a one-element batch. These assertions therefore cover the
+ * single-file path too; there is no separate one to diverge from.
+ */
+describe('Integration: runBatchLint (the lint adapter)', () => {
+    let projectDir;
+    // The exact diagnostic the enabled MissingContentForLayout check produces for a layout
+    // that omits `{{ content_for_layout }}`, reported at offset 0 (1-based line/column 1).
+    //
+    // Parameterised by `insertAt` because the check also SUGGESTS the insertion, and the
+    // engine's edit points at this buffer's `</body>` — so the expectation moves with the
+    // fixture rather than being a constant.
+    const missingContentForLayout = (insertAt) => ({
+        check: 'MissingContentForLayout',
+        severity: 'error',
+        message: "Layout is missing `{{ content_for_layout }}`. Every layout must output it exactly once — it renders the page body. (Named slots use `{% yield 'name' %}` separately and do not replace it.)",
+        line: 1,
+        column: 1,
+        end_line: 1,
+        end_column: 1,
+        suggestions: [
+            {
+                description: 'Insert `{{ content_for_layout }}` before the closing </body> tag',
+                edits: [
+                    { start_index: insertAt, end_index: insertAt, new_text: '{{ content_for_layout }}\n' },
+                ],
+            },
+        ],
+    });
+    /** `<html><body><header>Site</header>` — the offset of `</body>` in the longer fixture. */
+    const INSERT_AFTER_HEADER = 33;
+    /** `<html><body>` — the offset of `</body>` in the bare fixture. */
+    const INSERT_BARE_BODY = 12;
+    const LAYOUT = 'app/views/layouts/application.liquid';
+    beforeEach(() => {
+        projectDir = mkdtempSync(join(tmpdir(), 'mcp-sup-lint-'));
+        mkdirSync(join(projectDir, '.git'));
+        writeFileSync(join(projectDir, '.platformos-check.yml'), ['extends: platformos-check:nothing', 'MissingContentForLayout:', '  enabled: true', ''].join('\n'), 'utf8');
+    });
+    afterEach(() => {
+        rmSync(projectDir, { recursive: true, force: true });
+    });
+    const lint = (buffers) => runBatchLint({ projectDir, buffers });
+    it('maps a real offense to the exact diagnostic (check, severity, message, 1-based range)', async () => {
+        const byFile = await lint([
+            { filePath: LAYOUT, content: '<html><body><header>Site</header></body></html>' },
+        ]);
+        expect(byFile.diagnostics.get(LAYOUT)).toEqual([missingContentForLayout(INSERT_AFTER_HEADER)]);
+    });
+    it('returns no diagnostics for a clean layout', async () => {
+        const byFile = await lint([
+            { filePath: LAYOUT, content: '<html><body>{{ content_for_layout }}</body></html>' },
+        ]);
+        expect(byFile.diagnostics.get(LAYOUT)).toEqual([]);
+    });
+    it('returns an entry for every requested buffer, so "clean" is distinguishable from "not linted"', async () => {
+        const clean = 'app/views/layouts/clean.liquid';
+        const byFile = await lint([
+            { filePath: LAYOUT, content: '<html><body></body></html>' },
+            { filePath: clean, content: '<html>{{ content_for_layout }}</html>' },
+        ]);
+        expect([...byFile.diagnostics.keys()].sort()).toEqual([clean, LAYOUT].sort());
+        expect(byFile.diagnostics.get(clean)).toEqual([]);
+        expect(byFile.diagnostics.get(LAYOUT)).toEqual([missingContentForLayout(INSERT_BARE_BODY)]);
+    });
+    it('accepts an absolute file path and keys the result by that same string', async () => {
+        // Results are keyed by the CALLER's key, so a caller mixing relative and
+        // absolute paths can find its own results without reproducing our normalization.
+        const absolute = join(projectDir, LAYOUT);
+        mkdirSync(dirname(absolute), { recursive: true });
+        const byFile = await lint([{ filePath: absolute, content: '<html><body></body></html>' }]);
+        expect(byFile.diagnostics.get(absolute)).toEqual([missingContentForLayout(INSERT_BARE_BODY)]);
+    });
+    it('gives a relative and an absolute path for the SAME file identical diagnostics', async () => {
+        const absolute = join(projectDir, LAYOUT);
+        const content = '<html><body></body></html>';
+        const byFile = await lint([
+            { filePath: LAYOUT, content },
+            { filePath: absolute, content },
+        ]);
+        expect(byFile.diagnostics.get(LAYOUT)).toEqual(byFile.diagnostics.get(absolute));
+        expect(byFile.diagnostics.get(LAYOUT)).toEqual([missingContentForLayout(INSERT_BARE_BODY)]);
+    });
+    /**
+     * `sources` is optional on the TYPE, for the benefit of test stubs; the real adapter has
+     * no such licence.
+     *
+     * The alignment is the part that could go wrong silently: `startIndexes[i]` belongs to
+     * `diagnostics[i]`, and out of step, enrichment would resolve each diagnostic against
+     * another's node — a confidently wrong hint on a correct finding, with nothing failing.
+     */
+    it('populates sources for every file it reports diagnostics for, index-aligned', async () => {
+        const clean = 'app/views/layouts/clean.liquid';
+        const byFile = await lint([
+            { filePath: LAYOUT, content: '<html><body></body></html>' },
+            { filePath: clean, content: '<html>{{ content_for_layout }}</html>' },
+        ]);
+        expect([...byFile.diagnostics].map(([key, diagnostics]) => ({
+            key,
+            hasSource: byFile.sources?.has(key) ?? false,
+            aligned: byFile.sources?.get(key)?.startIndexes.length === diagnostics.length,
+        }))).toEqual([
+            { key: LAYOUT, hasSource: true, aligned: true },
+            { key: clean, hasSource: true, aligned: true },
+        ]);
+    });
+    /**
+     * `sources.ast` is the tree of the BUFFER, and the reason `LintBufferResult` hands one
+     * back instead of letting a caller read the `App` afterwards: the overlay is reverted
+     * before this returns, so a tree fetched later describes DISK — right on every unchanged
+     * file and wrong on exactly the ones being edited.
+     *
+     * The file on disk and the buffer carry DIFFERENT filter names, so a test reading the
+     * wrong tree cannot agree by accident.
+     */
+    it('returns the tree of the BUFFER, not of the file on disk', async () => {
+        const absolute = join(projectDir, LAYOUT);
+        mkdirSync(dirname(absolute), { recursive: true });
+        writeFileSync(absolute, '<html><body>{{ x | on_disk_filter }}</body></html>', 'utf8');
+        const byFile = await lint([
+            { filePath: LAYOUT, content: '<html><body>{{ x | in_buffer_filter }}</body></html>' },
+        ]);
+        const names = [];
+        const walk = (node) => {
+            if (!node || typeof node !== 'object')
+                return;
+            const candidate = node;
+            if (candidate.type === 'LiquidFilter' && typeof candidate.name === 'string') {
+                names.push(candidate.name);
+            }
+            for (const value of Object.values(node)) {
+                if (Array.isArray(value))
+                    value.forEach(walk);
+                else if (value && typeof value === 'object')
+                    walk(value);
+            }
+        };
+        walk(byFile.sources?.get(LAYOUT)?.ast);
+        expect(names).toEqual(['in_buffer_filter']);
+    });
+    it('returns an empty map for an empty request without touching the project', async () => {
+        expect(await lint([])).toEqual({
+            diagnostics: new Map(),
+            sources: new Map(),
+            notChecked: new Map(),
+        });
+    });
+});
+/**
+ * The engine's structured fixes have to REACH the agent.
+ *
+ * `Offense.fix` and `Offense.suggest` are `Fixer` functions, and an adapter that drops them
+ * returns English describing a change check-common had already computed to the character.
+ * Whole-value assertions on purpose: a fix is a set of edits, and "a fix is present" is not
+ * the property that matters. The offsets are.
+ */
+describe('Integration: runBatchLint — structured fixes and suggestions', () => {
+    let projectDir;
+    beforeEach(() => {
+        projectDir = mkdtempSync(join(tmpdir(), 'mcp-sup-fixes-'));
+        mkdirSync(join(projectDir, '.git'));
+        writeFileSync(join(projectDir, '.platformos-check.yml'), `extends: platformos-check:nothing
+JsonLiteralQuoteStyle:
+  enabled: true
+DeprecatedTag:
+  enabled: true
+DeprecatedFilter:
+  enabled: true
+ParserBlockingScript:
+  enabled: true
+`, 'utf8');
+    });
+    afterEach(() => {
+        rmSync(projectDir, { recursive: true, force: true });
+    });
+    const diagnose = async (filePath, content) => {
+        const { diagnostics } = await runBatchLint({ projectDir, buffers: [{ filePath, content }] });
+        return diagnostics.get(filePath);
+    };
+    /** Apply edits back-to-front, so earlier offsets are not shifted by later inserts. */
+    const applyEdits = (source, edits) => [...edits]
+        .sort((a, b) => b.start_index - a.start_index)
+        .reduce((out, edit) => out.slice(0, edit.start_index) + edit.new_text + out.slice(edit.end_index), source);
+    it('carries a single-edit autofix, with offsets into the buffer', async () => {
+        const source = "{% assign o = {'k': 1} %}{{ o }}";
+        expect(await diagnose('app/views/pages/json.liquid', source)).toEqual([
+            {
+                check: 'JsonLiteralQuoteStyle',
+                severity: 'error',
+                message: 'Use double quotes for string literals inside object/array literals (e.g. \'{"key": "value"}\', not "{\'key\': \'value\'}").',
+                line: 1,
+                column: 16,
+                end_line: 1,
+                end_column: 19,
+                fix: { edits: [{ start_index: 15, end_index: 18, new_text: '"k"' }] },
+            },
+        ]);
+    });
+    /**
+     * THE case that decided `AgentFix.edits` is a list rather than one edit.
+     *
+     * Renaming a block tag means renaming `end<name>` too — check-common's `renamesFor` says
+     * it outright — so a single-edit shape would have kept the first edit and dropped the
+     * second SILENTLY, handing an agent a fix that breaks the file. Measured frequency over
+     * three real projects: 15 of 6,238 fixes are multi-edit.
+     */
+    it('carries BOTH edits of a block-tag rename, and applying them produces valid source', async () => {
+        const source = '{% try_rc %}{% assign z = 1 %}{% endtry_rc %}';
+        const diagnostics = (await diagnose('app/views/pages/block.liquid', source)) ?? [];
+        expect(diagnostics).toEqual([
+            {
+                check: 'DeprecatedTag',
+                severity: 'warning',
+                message: "Deprecated tag 'try_rc': Use {% try %} instead.",
+                line: 1,
+                column: 4,
+                end_line: 1,
+                end_column: 10,
+                fix: {
+                    edits: [
+                        { start_index: 3, end_index: 9, new_text: 'try' },
+                        { start_index: 33, end_index: 42, new_text: 'endtry' },
+                    ],
+                },
+            },
+        ]);
+        // The edits are not merely present — they are correct. Applying them renames both
+        // halves, which is the only reason the fix is safe to hand an agent.
+        expect(applyEdits(source, diagnostics[0].fix.edits)).toEqual('{% try %}{% assign z = 1 %}{% endtry %}');
+    });
+    it('carries every suggestion the engine offers, each with its own description', async () => {
+        const source = '<script src="a.js"></script>';
+        expect(await diagnose('app/views/pages/script.liquid', source)).toEqual([
+            {
+                check: 'ParserBlockingScript',
+                severity: 'error',
+                message: 'Avoid parser blocking scripts by adding `defer` or `async` on this tag',
+                line: 1,
+                column: 1,
+                end_line: 1,
+                end_column: 29,
+                suggestions: [
+                    {
+                        description: 'Use an HTML script tag with the defer attribute instead',
+                        edits: [{ start_index: 18, end_index: 18, new_text: ' defer' }],
+                    },
+                    {
+                        description: 'Use an HTML script tag with the async attribute instead',
+                        edits: [{ start_index: 18, end_index: 18, new_text: ' async' }],
+                    },
+                ],
+            },
+        ]);
+    });
+    /**
+     * The CONTROL for every assertion above: a diagnostic the engine offers nothing for comes
+     * back with neither key. `DeprecatedFilter` on `parse_json` is that case — upstream
+     * publishes no successor filter, so the check reports without a fix.
+     *
+     * Without this, "the fix fields are populated" could be satisfied by populating them
+     * unconditionally.
+     */
+    it('omits fix and suggestions entirely when the engine offered neither', async () => {
+        expect(await diagnose('app/views/pages/nofix.liquid', "{{ 'x' | parse_json }}")).toEqual([
+            {
+                check: 'DeprecatedFilter',
+                severity: 'warning',
+                message: "Deprecated filter 'parse_json'.",
+                line: 1,
+                column: 8,
+                end_line: 1,
+                end_column: 20,
+            },
+        ]);
+    });
+    /**
+     * Offsets index the BUFFER, never the file on disk.
+     *
+     * The two differ on every `validate_code` call — that is what the tool is for — and a
+     * fix computed against the saved file would land at plausible-looking, wrong offsets.
+     * The on-disk copy here is deliberately longer, so an offset taken from it would not
+     * merely differ but point inside the wrong token.
+     */
+    it('computes edits against the sent buffer, not the file on disk', async () => {
+        const filePath = 'app/views/pages/stale.liquid';
+        const onDisk = join(projectDir, filePath);
+        mkdirSync(dirname(onDisk), { recursive: true });
+        writeFileSync(onDisk, "{% comment %}padding padding{% endcomment %}{% assign o = {'k': 1} %}", 'utf8');
+        const buffer = "{% assign o = {'k': 1} %}";
+        const diagnostics = (await diagnose(filePath, buffer)) ?? [];
+        expect(diagnostics.map((d) => d.fix)).toEqual([
+            { edits: [{ start_index: 15, end_index: 18, new_text: '"k"' }] },
+        ]);
+        expect(applyEdits(buffer, diagnostics[0].fix.edits)).toEqual('{% assign o = {"k": 1} %}');
+    });
+});
+/**
+ * ONE lint pass per request, and the correctness that follows from it.
+ *
+ * Everything expensive is per-PROJECT, so a changeset is overlaid all at once and linted
+ * once. That is a performance argument, but more importantly a CORRECTNESS one: with every
+ * buffer in the app at the same time, a partial being created in one resolves for the
+ * `{% render %}` in another.
+ *
+ * Asserted behaviourally rather than by counting calls into check-node, which would pin an
+ * implementation detail through a package boundary and still not say whether the shared
+ * pass produced a shared VIEW of the project.
+ *
+ * The two halves are a matched pair: the CONTROL shows `MissingPartial` genuinely fires for
+ * this fixture when the files are sent separately, so the silence in the batched case is
+ * caused by the batching and not by a fixture with nothing to report.
+ */
+describe('Integration: runBatchLint — one pass, one shared view of the project', () => {
+    let projectDir;
+    const CALLER = 'app/views/pages/home.liquid';
+    const PARTIAL = 'app/views/partials/brand_new.liquid';
+    const CALLER_SOURCE = "{% render 'brand_new' %}";
+    const PARTIAL_SOURCE = '<div>hello</div>';
+    beforeEach(() => {
+        projectDir = mkdtempSync(join(tmpdir(), 'mcp-sup-batch-'));
+        mkdirSync(join(projectDir, '.git'));
+        writeFileSync(join(projectDir, '.platformos-check.yml'), ['extends: platformos-check:nothing', 'MissingPartial:', '  enabled: true', ''].join('\n'), 'utf8');
+    });
+    afterEach(() => {
+        rmSync(projectDir, { recursive: true, force: true });
+    });
+    it('resolves a partial created in the SAME request, so a coherent changeset is not reported broken', async () => {
+        const { diagnostics } = await runBatchLint({
+            projectDir,
+            buffers: [
+                { filePath: CALLER, content: CALLER_SOURCE },
+                { filePath: PARTIAL, content: PARTIAL_SOURCE },
+            ],
+        });
+        expect({ caller: diagnostics.get(CALLER), partial: diagnostics.get(PARTIAL) }).toEqual({
+            caller: [],
+            partial: [],
+        });
+    });
+    it('CONTROL: the same caller sent alone IS reported as rendering a missing partial', async () => {
+        const { diagnostics } = await runBatchLint({
+            projectDir,
+            buffers: [{ filePath: CALLER, content: CALLER_SOURCE }],
+        });
+        expect(diagnostics.get(CALLER)).toEqual([
+            {
+                check: 'MissingPartial',
+                severity: 'error',
+                message: "'brand_new' does not exist",
+                line: 1,
+                column: 11,
+                end_line: 1,
+                end_column: 22,
+            },
+        ]);
+    });
+});
+/**
+ * Line endings must not change a single number an agent reads.
+ *
+ * The agent-facing half of a defect in check-common's shared offset-to-position mapping: a
+ * carriage return was counted as a character of the line it terminates, so any diagnostic
+ * landing on a terminator came back one column further right under CRLF. The language
+ * server never showed it — the LSP clamps an over-long character — but this layer publishes
+ * a 1-based column with no clamp.
+ *
+ * Pinned HERE as well as in check-common because the two consumers disagree about what the
+ * numbers mean (0-based there, 1-based after `toDiagnostic`), so a fix made for one moves
+ * the other silently.
+ */
+describe('Integration: runBatchLint — CRLF and LF are indistinguishable', () => {
+    let projectDir;
+    beforeEach(() => {
+        projectDir = mkdtempSync(join(tmpdir(), 'mcp-sup-crlf-'));
+        mkdirSync(join(projectDir, '.git'));
+        writeFileSync(join(projectDir, '.platformos-check.yml'), `extends: platformos-check:nothing
+YAMLSyntaxError:
+  enabled: true
+LiquidHTMLSyntaxError:
+  enabled: true
+`, 'utf8');
+    });
+    afterEach(() => {
+        rmSync(projectDir, { recursive: true, force: true });
+    });
+    const diagnose = async (filePath, content) => {
+        const { diagnostics } = await runBatchLint({ projectDir, buffers: [{ filePath, content }] });
+        return diagnostics.get(filePath);
+    };
+    /**
+     * Each case is one source written twice, differing ONLY in line endings. The
+     * fixtures deliberately span both defect classes: an offset landing on the
+     * terminator, an offset at end of input, and a mid-line offset as the control that
+     * proves nothing else moved.
+     */
+    const CASES = [
+        {
+            name: 'unclosed flow sequence (end of input)',
+            file: 'app/schema/flow.yml',
+            lf: 'c: [1, 2\n',
+            expected: [
+                {
+                    check: 'YAMLSyntaxError',
+                    severity: 'error',
+                    message: 'Flow sequence in block collection must be sufficiently indented and end with a ]',
+                    line: 2,
+                    column: 1,
+                    end_line: 2,
+                    end_column: 1,
+                },
+            ],
+        },
+        {
+            name: 'unterminated quote (end of input)',
+            file: 'app/schema/quote.yml',
+            lf: 'name: "oops\n',
+            expected: [
+                {
+                    check: 'YAMLSyntaxError',
+                    severity: 'error',
+                    message: 'Missing closing "quote',
+                    line: 2,
+                    column: 1,
+                    end_line: 2,
+                    end_column: 1,
+                },
+            ],
+        },
+        {
+            name: 'tab indentation (mid-line — the control)',
+            file: 'app/schema/tab.yml',
+            lf: 'a:\n\tb: 1\n',
+            expected: [
+                {
+                    check: 'YAMLSyntaxError',
+                    severity: 'error',
+                    message: 'Tabs are not allowed as indentation',
+                    line: 2,
+                    column: 1,
+                    end_line: 2,
+                    end_column: 2,
+                },
+            ],
+        },
+        {
+            name: 'unclosed liquid tag (span ending on the terminator)',
+            file: 'app/views/pages/tag.liquid',
+            lf: '{% if x \n',
+            expected: [
+                {
+                    check: 'LiquidHTMLSyntaxError',
+                    severity: 'error',
+                    message: 'SyntaxError: expected "%}"',
+                    line: 1,
+                    column: 9,
+                    end_line: 2,
+                    end_column: 1,
+                },
+            ],
+        },
+    ];
+    for (const { name, file, lf, expected } of CASES) {
+        it(`reports the same diagnostic under LF and CRLF — ${name}`, async () => {
+            const crlfFile = file.replace(/\.(yml|liquid)$/, '_crlf.$1');
+            expect({
+                lf: await diagnose(file, lf),
+                crlf: await diagnose(crlfFile, lf.replace(/\n/g, '\r\n')),
+            }).toEqual({ lf: expected, crlf: expected });
+        });
+    }
+    it('never publishes a column past the end of the line it points at', async () => {
+        // The property the equalities above are instances of, stated directly so a future
+        // fixture cannot satisfy LF === CRLF while both halves are wrong. A 1-based column may
+        // be at most `line length + 1` — the end-of-line insertion point — with the line
+        // measured WITHOUT its terminator. Every source here puts a diagnostic ON a terminator,
+        // which is the only place the old mapping could overrun.
+        const sources = [
+            ['app/schema/bounds_flow.yml', 'c: [1, 2\r\n'],
+            ['app/schema/bounds_quote.yml', 'name: "oops\r\n'],
+            ['app/views/pages/bounds_tag.liquid', '{% if x \r\n'],
+        ];
+        const overruns = [];
+        for (const [filePath, source] of sources) {
+            const lines = source.split('\r\n');
+            const diagnostics = (await diagnose(filePath, source)) ?? [];
+            overruns.push(...diagnostics
+                .filter(({ line, column }) => column > (lines[line - 1] ?? '').length + 1)
+                .map(({ check, line, column }) => ({ filePath, check, line, column })));
+        }
+        expect(overruns).toEqual([]);
+    });
+});
+//# sourceMappingURL=lint-batch.spec.js.map

package/dist/lint/lint.d.ts

@@ -1,3 +1,4 @@
+import { type LintBufferStatus } from '@platformos/platformos-check-node';
 import type { ValidateCodeDiagnostic } from '../result/types.js';
 export interface RunLintParams {
     /** Absolute project root the buffer is validated against. */
@@ -7,5 +8,14 @@ export interface RunLintParams {
     /** In-memory buffer contents. */
     content: string;
 }
+export interface LintOutcome {
+    diagnostics: ValidateCodeDiagnostic[];
+    /**
+     * Set when the seam did NOT check the file, with its reason. An agent asked
+     * whether a file is correct, so "no diagnostics" and "nothing was looked at"
+     * cannot arrive as the same answer — see `lintBuffer`'s `LintBufferStatus`.
+     */
+    notChecked?: Exclude<LintBufferStatus, 'checked'>;
+}
 /** Lint the buffer and return the mapped diagnostics for the file. */
-export declare function runLint(params: RunLintParams): Promise<ValidateCodeDiagnostic[]>;
+export declare function runLint(params: RunLintParams): Promise<LintOutcome>;

package/dist/lint/lint.js

@@ -13,7 +13,7 @@
  * `Offense.fix` / `suggest` are intentionally not translated.
  */
 import { isAbsolute, join } from 'node:path';
-import { lintBuffer, Severity } from '@platformos/platformos-check-node';
+import { lintBuffer, Severity, } from '@platformos/platformos-check-node';
 const SEVERITY = {
     [Severity.ERROR]: 'error',
     [Severity.WARNING]: 'warning',
@@ -23,8 +23,14 @@ const SEVERITY = {
 export async function runLint(params) {
     const { projectDir, filePath, content } = params;
     const absoluteFilePath = isAbsolute(filePath) ? filePath : join(projectDir, filePath);
-    const offenses = await lintBuffer({ root: projectDir, filePath: absoluteFilePath, content });
-    return offenses.map(toDiagnostic);
+    const { status, offenses } = await lintBuffer({
+        root: projectDir,
+        filePath: absoluteFilePath,
+        content,
+    });
+    if (status !== 'checked')
+        return { diagnostics: [], notChecked: status };
+    return { diagnostics: offenses.map(toDiagnostic) };
 }
 /**
  * Map a check-common `Offense` to a `ValidateCodeDiagnostic`.

package/dist/result/assemble.d.ts

@@ -1,13 +1,15 @@
+import type { Declined, ValidateCodeDiagnostic, ValidateCodeImpact, ValidateCodeResult } from './types.js';
+export declare function assembleResult(diagnostics: ValidateCodeDiagnostic[], impact: ValidateCodeImpact): ValidateCodeResult;
 /**
- * Result assembly (minimal "lint only" slice).
+ * The result for a file this server did NOT check — outside the project root, not a
+ * platformOS source type, too large to parse safely, or past its deadline (see
+ * `fileApplicability` / `bufferTooLarge` / `withDeadline`).
  *
- * Buckets the mapped diagnostics into errors / warnings / infos and derives the
- * `status` + `must_fix_before_write` envelope. PURE — no I/O, consumes only the
- * diagnostic list and the shared result types.
+ * Everything is empty and `must_fix_before_write` is `false`, so the call neither blocks
+ * the write nor approves it — including for a TIMEOUT, since blocking a write because our
+ * own validation failed would make the tool a liability. `reason` lands in `next_step`;
+ * `code` lands in `not_applicable_reason` for an agent to branch on.
  *
- * The ergonomic transforms (clustering, scorecard, the explicit
- * blocking-warning set, `next_step`, tips, domain_guide, structural) are added
- * in later tasks; they are left empty/null here.
+ * `impact` is `not_applicable`: nothing cross-file was compared either.
  */
-import type { ValidateCodeDiagnostic, ValidateCodeMode, ValidateCodeResult } from './types.js';
-export declare function assembleResult(diagnostics: ValidateCodeDiagnostic[], _mode: ValidateCodeMode): ValidateCodeResult;
+export declare function assembleNotApplicableResult(declined: Declined): ValidateCodeResult;

package/dist/result/assemble.js

@@ -1,25 +1,72 @@
-export function assembleResult(diagnostics, 
-// Reserved: `full`/`quick` do not yet change output (no heavier stages exist).
-_mode) {
-    const errors = diagnostics.filter((d) => d.severity === 'error');
-    const warnings = diagnostics.filter((d) => d.severity === 'warning');
-    const infos = diagnostics.filter((d) => d.severity === 'info');
+/**
+ * Result assembly.
+ *
+ * Buckets the mapped diagnostics into errors / warnings / infos and derives the `status` +
+ * `must_fix_before_write` envelope. PURE — no I/O, consumes only the diagnostic list and
+ * the shared result types. `impact` is pre-computed by the impact adapter and included
+ * verbatim.
+ *
+ * The result carries ONLY fields that are actually populated: an agent cannot tell an
+ * always-empty field from a meaningful one.
+ */
+import { blocksWrite } from './blocking.js';
+import { NOT_APPLICABLE_IMPACT } from './impact-states.js';
+/**
+ * Order diagnostics the way someone READS the file: top to bottom, left to right.
+ *
+ * `check()` collects results per check, so the raw order is grouped by check code — an
+ * `ImgWidthAndHeight` on line 5 arrives before a `MissingPartial` on line 1.
+ *
+ * Sorting belongs HERE rather than in check-common: the engine's job is detection, and
+ * per-check batching is what makes it fast. `check` is the final tiebreak so two findings
+ * at the identical position have a deterministic order across runs.
+ */
+function inReadingOrder(diagnostics) {
+    return [...diagnostics].sort((a, b) => a.line - b.line || a.column - b.column || a.check.localeCompare(b.check));
+}
+export function assembleResult(diagnostics, impact) {
+    const ordered = inReadingOrder(diagnostics);
+    const errors = ordered.filter((d) => d.severity === 'error');
+    const warnings = ordered.filter((d) => d.severity === 'warning');
+    const infos = ordered.filter((d) => d.severity === 'info');
+    // `ok` MEANS "checked, nothing objected" — honest only while every file type this server
+    // admits has at least one check that examines it. That is an INVARIANT, not a fact, and
+    // `transport/validate-code.spec.ts`'s file-type-coverage group fails if a type is ever
+    // admitted with nothing looking at it. Read it before adding a `PlatformOSFileType`.
     const status = errors.length > 0 ? 'error' : warnings.length > 0 ? 'warning' : 'ok';
     return {
         status,
-        // Minimal gate: any error blocks the write. The richer blocking-warning set
-        // is defined in the result-assembly task.
-        must_fix_before_write: errors.length > 0,
+        // NOT `errors.length > 0`. `status` says what was FOUND; this says whether the file is
+        // broken, which is a strictly smaller question — see `blocking.ts`.
+        must_fix_before_write: blocksWrite(errors),
         errors,
         warnings,
         infos,
-        proposed_fixes: [],
-        clusters: [],
-        scorecard: [],
-        parse_error: null,
-        tips: [],
-        domain_guide: null,
-        structural: null,
+        impact,
+    };
+}
+/**
+ * The result for a file this server did NOT check — outside the project root, not a
+ * platformOS source type, too large to parse safely, or past its deadline (see
+ * `fileApplicability` / `bufferTooLarge` / `withDeadline`).
+ *
+ * Everything is empty and `must_fix_before_write` is `false`, so the call neither blocks
+ * the write nor approves it — including for a TIMEOUT, since blocking a write because our
+ * own validation failed would make the tool a liability. `reason` lands in `next_step`;
+ * `code` lands in `not_applicable_reason` for an agent to branch on.
+ *
+ * `impact` is `not_applicable`: nothing cross-file was compared either.
+ */
+export function assembleNotApplicableResult(declined) {
+    return {
+        status: 'not_applicable',
+        not_applicable_reason: declined.code,
+        must_fix_before_write: false,
+        errors: [],
+        warnings: [],
+        infos: [],
+        impact: NOT_APPLICABLE_IMPACT(),
+        next_step: declined.reason,
     };
 }
 //# sourceMappingURL=assemble.js.map

package/dist/result/assemble.spec.d.ts

@@ -0,0 +1 @@
+export {};