@platformos/platformos-mcp-supervisor 0.0.2 → 0.2.0

package/dist/impact/impact.spec.js

@@ -0,0 +1,357 @@
+import { mkdirSync, mkdtempSync, 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 { NodeFileSystem, path as pathUtils } from '@platformos/platformos-check-node';
+import { runImpact } from './impact.js';
+import { createProjectScan } from './project-scan.js';
+/**
+ * The blast radius is an I/O adapter over the project's own text, so these run against a
+ * REAL project on disk rather than a stubbed graph.
+ *
+ * A stubbed `AppGraph` can only prove the summarizing arithmetic; every claim that matters
+ * — that a `{% render %}` in another file is FOUND, that a name-shaped substring in prose
+ * is not, that a buffer's edit is what counts — lives below the stub. Here the walk, the
+ * read, the name filter, the parse and the resolver all run.
+ */
+describe('runImpact', () => {
+    let projectDir;
+    beforeEach(() => {
+        projectDir = mkdtempSync(join(tmpdir(), 'pos-impact-'));
+    });
+    afterEach(() => {
+        rmSync(projectDir, { recursive: true, force: true });
+    });
+    const write = (files) => {
+        for (const [relativePath, source] of Object.entries(files)) {
+            const absolute = join(projectDir, relativePath);
+            mkdirSync(dirname(absolute), { recursive: true });
+            writeFileSync(absolute, source, 'utf8');
+        }
+    };
+    const scanOf = (buffers = {}) => createProjectScan(pathUtils.normalize(pathUtils.toUri(projectDir)), NodeFileSystem, new Map(Object.entries(buffers).map(([relativePath, content]) => [
+        pathUtils.normalize(pathUtils.toUri(join(projectDir, relativePath))),
+        content,
+    ])));
+    const run = (filePath, content = '', scan = scanOf()) => runImpact({ projectDir, filePath, content }, scan);
+    const card = 'app/views/partials/card.liquid';
+    describe('dependents', () => {
+        it('summarizes distinct dependent files, per-kind counts, and a sorted sample', async () => {
+            write({
+                [card]: '<div></div>',
+                'app/views/pages/index.liquid': "{% render 'card' %}",
+                'app/views/pages/about.liquid': "{% render 'card' %}",
+                'app/views/partials/wrapper.liquid': "{% include 'card' %}",
+            });
+            expect(await run(card)).toEqual({
+                scope: 'direct',
+                status: 'computed',
+                dependents: {
+                    total: 3,
+                    by_kind: { render: 2, include: 1 },
+                    sample: [
+                        'app/views/pages/about.liquid',
+                        'app/views/pages/index.liquid',
+                        'app/views/partials/wrapper.liquid',
+                    ],
+                },
+            });
+        });
+        it('reports computed with zero dependents (safe to change), distinct from "not computed"', async () => {
+            write({ [card]: '<div></div>', 'app/views/pages/index.liquid': '<p>nothing here</p>' });
+            expect(await run(card)).toEqual({
+                scope: 'direct',
+                status: 'computed',
+                dependents: { total: 0, by_kind: {}, sample: [] },
+            });
+        });
+        it('counts a file once in total but under each kind it references by', async () => {
+            write({
+                [card]: '<div></div>',
+                // same caller, two render edges → one distinct file
+                'app/views/pages/index.liquid': "{% render 'card' %}{% render 'card' %}",
+                // a caller that both renders and includes → one file, counted in both kinds
+                'app/views/partials/dual.liquid': "{% render 'card' %}{% include 'card' %}",
+            });
+            expect(await run(card)).toEqual({
+                scope: 'direct',
+                status: 'computed',
+                dependents: {
+                    total: 2,
+                    by_kind: { render: 2, include: 1 },
+                    sample: ['app/views/pages/index.liquid', 'app/views/partials/dual.liquid'],
+                },
+            });
+        });
+        it('caps the sample at 10 files while keeping the true total', async () => {
+            write({
+                [card]: '<div></div>',
+                ...Object.fromEntries(Array.from({ length: 15 }, (_, i) => [
+                    `app/views/pages/p${String(i).padStart(2, '0')}.liquid`,
+                    "{% render 'card' %}",
+                ])),
+            });
+            expect(await run(card)).toEqual({
+                scope: 'direct',
+                status: 'computed',
+                dependents: {
+                    total: 15,
+                    by_kind: { render: 15 },
+                    sample: [
+                        'app/views/pages/p00.liquid',
+                        'app/views/pages/p01.liquid',
+                        'app/views/pages/p02.liquid',
+                        'app/views/pages/p03.liquid',
+                        'app/views/pages/p04.liquid',
+                        'app/views/pages/p05.liquid',
+                        'app/views/pages/p06.liquid',
+                        'app/views/pages/p07.liquid',
+                        'app/views/pages/p08.liquid',
+                        'app/views/pages/p09.liquid',
+                    ],
+                },
+            });
+        });
+        /**
+         * The name filter is an over-approximation, so everything past it must be
+         * EXACT. A file that merely spells the name — in prose, or as the prefix of a
+         * different partial's name — survives the filter and must contribute nothing.
+         *
+         * The control is the third file: the same fixture proves a real `{% render %}`
+         * IS found, so "zero" here cannot be the scan quietly finding nothing at all.
+         */
+        it('does not count a file that only mentions the name without referencing it', async () => {
+            write({
+                [card]: '<div></div>',
+                'app/views/pages/prose.liquid': '<p>the card component is documented elsewhere</p>',
+                'app/views/pages/prefix.liquid': "{% render 'card_footer' %}",
+                'app/views/partials/card_footer.liquid': '<footer></footer>',
+                'app/views/pages/real.liquid': "{% render 'card' %}",
+            });
+            expect(await run(card)).toEqual({
+                scope: 'direct',
+                status: 'computed',
+                dependents: {
+                    total: 1,
+                    by_kind: { render: 1 },
+                    sample: ['app/views/pages/real.liquid'],
+                },
+            });
+        });
+        it('finds callers through every edge kind, not just render/include', async () => {
+            write({
+                'app/graphql/get_posts.graphql': 'query { posts { id } }',
+                'app/views/pages/index.liquid': "{% graphql posts = 'get_posts' %}",
+            });
+            expect(await run('app/graphql/get_posts.graphql')).toEqual({
+                scope: 'direct',
+                status: 'computed',
+                dependents: {
+                    total: 1,
+                    by_kind: { graphql: 1 },
+                    sample: ['app/views/pages/index.liquid'],
+                },
+            });
+        });
+        it('finds a caller in a module, whose reference spells the modules/<name>/ prefix', async () => {
+            write({
+                'modules/core/public/views/partials/badge.liquid': '<span></span>',
+                'app/views/pages/index.liquid': "{% render 'modules/core/badge' %}",
+            });
+            expect(await run('modules/core/public/views/partials/badge.liquid')).toEqual({
+                scope: 'direct',
+                status: 'computed',
+                dependents: {
+                    total: 1,
+                    by_kind: { render: 1 },
+                    sample: ['app/views/pages/index.liquid'],
+                },
+            });
+        });
+    });
+    describe('the changeset is what counts, not just disk', () => {
+        it('counts a caller the buffer has just added', async () => {
+            write({ [card]: '<div></div>', 'app/views/pages/index.liquid': '<p>nothing yet</p>' });
+            const scan = scanOf({ 'app/views/pages/index.liquid': "{% render 'card' %}" });
+            expect(await run(card, '', scan)).toEqual({
+                scope: 'direct',
+                status: 'computed',
+                dependents: {
+                    total: 1,
+                    by_kind: { render: 1 },
+                    sample: ['app/views/pages/index.liquid'],
+                },
+            });
+        });
+        it('stops counting a caller whose reference the buffer has just deleted', async () => {
+            write({ [card]: '<div></div>', 'app/views/pages/index.liquid': "{% render 'card' %}" });
+            const scan = scanOf({ 'app/views/pages/index.liquid': '<p>not any more</p>' });
+            expect(await run(card, '', scan)).toEqual({
+                scope: 'direct',
+                status: 'computed',
+                dependents: { total: 0, by_kind: {}, sample: [] },
+            });
+        });
+        it('counts a caller that does not exist on disk at all yet', async () => {
+            write({ [card]: '<div></div>' });
+            const scan = scanOf({ 'app/views/pages/brand-new.liquid': "{% render 'card' %}" });
+            expect(await run(card, '', scan)).toEqual({
+                scope: 'direct',
+                status: 'computed',
+                dependents: {
+                    total: 1,
+                    by_kind: { render: 1 },
+                    sample: ['app/views/pages/brand-new.liquid'],
+                },
+            });
+        });
+    });
+    describe('applicability (files nothing can reference by name)', () => {
+        /**
+         * A scan that throws if it is consulted — applicability is a property of the
+         * FILE, decided before any project text is read.
+         */
+        const throwingScan = () => ({
+            rootUri: pathUtils.normalize(pathUtils.toUri(projectDir)),
+            fs: NodeFileSystem,
+            sources: () => {
+                throw new Error('the project must not be scanned for a non-trackable file');
+            },
+        });
+        it('reports not_applicable for a custom-model-type/schema YAML (wired by table name, not by edge)', async () => {
+            expect(await run('app/custom_model_types/blog_post.yml', '', throwingScan())).toEqual({
+                scope: 'direct',
+                status: 'not_applicable',
+                dependents: { total: 0, by_kind: {}, sample: [] },
+            });
+        });
+        it('reports not_applicable for a translation YAML', async () => {
+            expect(await run('app/translations/en.yml', '', throwingScan())).toEqual({
+                scope: 'direct',
+                status: 'not_applicable',
+                dependents: { total: 0, by_kind: {}, sample: [] },
+            });
+        });
+        it('reports not_applicable for a Liquid file in no platformOS directory — it has no name to reference', async () => {
+            expect(await run('scripts/generate.liquid', '', throwingScan())).toEqual({
+                scope: 'direct',
+                status: 'not_applicable',
+                dependents: { total: 0, by_kind: {}, sample: [] },
+            });
+        });
+    });
+    describe('signature-impact (callers vs the edited buffer {% doc %})', () => {
+        // A buffer declaring `title` (required) and `count` (optional).
+        const docBuffer = `{% doc %}
+  @param {String} title - required title
+  @param {Number} [count] - optional count
+{% enddoc %}
+<div>{{ title }}</div>`;
+        it('flags dependent callers that omit a required @param or pass an undeclared one', async () => {
+            write({
+                [card]: '<div></div>',
+                // ok: passes the required title
+                'app/views/pages/ok.liquid': "{% render 'card', title: 'a', count: 1 %}",
+                // missing required `title`
+                'app/views/pages/missing.liquid': "{% render 'card', count: 1 %}",
+                // passes an argument the doc does not declare
+                'app/views/pages/extra.liquid': "{% render 'card', title: 'a', colour: 'red' %}",
+                // passes nothing at all → missing required `title`
+                'app/views/pages/bare.liquid': "{% render 'card' %}",
+            });
+            expect(await run(card, docBuffer)).toEqual({
+                scope: 'direct',
+                status: 'computed',
+                dependents: {
+                    total: 4,
+                    by_kind: { render: 4 },
+                    sample: [
+                        'app/views/pages/bare.liquid',
+                        'app/views/pages/extra.liquid',
+                        'app/views/pages/missing.liquid',
+                        'app/views/pages/ok.liquid',
+                    ],
+                },
+                signature_risk: [
+                    {
+                        caller: 'app/views/pages/bare.liquid',
+                        missing_required: ['title'],
+                        unexpected_args: [],
+                    },
+                    {
+                        caller: 'app/views/pages/extra.liquid',
+                        missing_required: [],
+                        unexpected_args: ['colour'],
+                    },
+                    {
+                        caller: 'app/views/pages/missing.liquid',
+                        missing_required: ['title'],
+                        unexpected_args: [],
+                    },
+                ],
+            });
+        });
+        it('returns an empty signature_risk (checked, all match) when every caller satisfies the doc', async () => {
+            write({
+                [card]: '<div></div>',
+                'app/views/pages/a.liquid': "{% render 'card', title: 'a' %}",
+                'app/views/pages/b.liquid': "{% render 'card', title: 'b', count: 2 %}",
+            });
+            expect((await run(card, docBuffer)).signature_risk).toEqual([]);
+        });
+        it('omits signature_risk entirely when the buffer declares no {% doc %} contract', async () => {
+            write({
+                [card]: '<div></div>',
+                'app/views/pages/x.liquid': "{% render 'card', whatever: 1 %}",
+            });
+            const result = await run(card, '<div>{{ title }}</div>');
+            expect(result.signature_risk).toBeUndefined();
+            expect(result.status).toEqual('computed');
+        });
+        it('ignores non-@param edges (background/graphql) — only render/include/function args are @params', async () => {
+            write({
+                [card]: '<div></div>',
+                // render caller passing an undeclared arg → flagged
+                'app/views/pages/render.liquid': "{% render 'card', title: 'a', colour: 'red' %}",
+                // background caller: `delay` is a scheduling arg, NOT a @param → must NOT be flagged
+                'app/views/pages/bg.liquid': "{% background job = 'card', delay: 5 %}",
+                // graphql caller: `per_page` is an operation arg, NOT a @param → must NOT be flagged
+                'app/views/pages/gql.liquid': "{% graphql g = 'card', per_page: 10 %}",
+            });
+            // background/graphql callers ARE still counted as dependents — they are only
+            // excluded from the @param signature check.
+            const result = await run(card, docBuffer);
+            expect(result.dependents.by_kind).toEqual({ render: 1, background: 1 });
+            expect(result.signature_risk).toEqual([
+                {
+                    caller: 'app/views/pages/render.liquid',
+                    missing_required: [],
+                    unexpected_args: ['colour'],
+                },
+            ]);
+        });
+        it('includes function call sites (their args ARE @params, mirroring PartialCallArguments)', async () => {
+            write({
+                [card]: '<div></div>',
+                'app/lib/commands/run.liquid': "{% function r = 'card', count: 1 %}",
+            });
+            expect(await run(card, docBuffer)).toEqual({
+                scope: 'direct',
+                status: 'computed',
+                dependents: {
+                    total: 1,
+                    by_kind: { function: 1 },
+                    sample: ['app/lib/commands/run.liquid'],
+                },
+                signature_risk: [
+                    {
+                        caller: 'app/lib/commands/run.liquid',
+                        missing_required: ['title'],
+                        unexpected_args: [],
+                    },
+                ],
+            });
+        });
+    });
+});
+//# sourceMappingURL=impact.spec.js.map

package/dist/impact/project-scan.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The project's edge-source files as TEXT, read ONCE per request.
+ *
+ * This is the whole of impact's project state, and it is read only when some buffer in the
+ * request could HAVE dependants — decidable from the paths alone, before any I/O. The trade
+ * is deliberate:
+ * pay a project READ per request — I/O, on the threadpool, overlapping the lint's CPU —
+ * instead of a whole-project PARSE once and a lifetime of keeping it honest. Measured on a
+ * real project (2,615 edge sources, 3.0 MB): 235 ms. Being derived per request, it cannot be
+ * stale, which is why `impact` has no `computing` state.
+ *
+ * SCOPE. Only EDGE SOURCES are read (`enumerateEdgeSources` — page/layout/partial), because
+ * only their content can declare an edge; `.graphql`/`.yml`/asset files are leaves and can
+ * never be the SOURCE of a reference. That is the graph's own definition, imported rather
+ * than restated.
+ *
+ * BUFFERS WIN OVER DISK. The changeset under validation is overlaid, so a call a buffer has
+ * only just added counts, and one it has just deleted stops counting — otherwise this stage
+ * would answer from disk while the lint beside it answers from the buffer. A buffer for a
+ * file not yet on disk is ADDED when it is an edge source, so a brand-new page's
+ * `{% render %}` is seen.
+ */
+import { type UriString } from '@platformos/platformos-check-common';
+import type { AbstractFileSystem } from '@platformos/platformos-common';
+/** The project text one request works from, plus the filesystem name resolution reads through. */
+export interface ProjectScan {
+    readonly rootUri: UriString;
+    readonly fs: AbstractFileSystem;
+    /** Every edge source's text, keyed by normalized URI. Memoized: read once per scan. */
+    sources(): Promise<ReadonlyMap<UriString, string>>;
+}
+/**
+ * A scan of `rootUri`, with `buffers` (normalized URI → in-flight content) overlaid.
+ *
+ * Nothing is read until {@link ProjectScan.sources} is first called, and it is read exactly
+ * once however many buffers a request validates — the reason the scan is a request-scoped
+ * object rather than a free function.
+ */
+export declare function createProjectScan(rootUri: UriString, fs: AbstractFileSystem, buffers?: ReadonlyMap<UriString, string>): ProjectScan;

package/dist/impact/project-scan.js

@@ -0,0 +1,62 @@
+/**
+ * The project's edge-source files as TEXT, read ONCE per request.
+ *
+ * This is the whole of impact's project state, and it is read only when some buffer in the
+ * request could HAVE dependants — decidable from the paths alone, before any I/O. The trade
+ * is deliberate:
+ * pay a project READ per request — I/O, on the threadpool, overlapping the lint's CPU —
+ * instead of a whole-project PARSE once and a lifetime of keeping it honest. Measured on a
+ * real project (2,615 edge sources, 3.0 MB): 235 ms. Being derived per request, it cannot be
+ * stale, which is why `impact` has no `computing` state.
+ *
+ * SCOPE. Only EDGE SOURCES are read (`enumerateEdgeSources` — page/layout/partial), because
+ * only their content can declare an edge; `.graphql`/`.yml`/asset files are leaves and can
+ * never be the SOURCE of a reference. That is the graph's own definition, imported rather
+ * than restated.
+ *
+ * BUFFERS WIN OVER DISK. The changeset under validation is overlaid, so a call a buffer has
+ * only just added counts, and one it has just deleted stops counting — otherwise this stage
+ * would answer from disk while the lint beside it answers from the buffer. A buffer for a
+ * file not yet on disk is ADDED when it is an edge source, so a brand-new page's
+ * `{% render %}` is seen.
+ */
+import { path } from '@platformos/platformos-check-common';
+import { enumerateEdgeSources, isEdgeSource } from '@platformos/platformos-graph';
+/**
+ * A scan of `rootUri`, with `buffers` (normalized URI → in-flight content) overlaid.
+ *
+ * Nothing is read until {@link ProjectScan.sources} is first called, and it is read exactly
+ * once however many buffers a request validates — the reason the scan is a request-scoped
+ * object rather than a free function.
+ */
+export function createProjectScan(rootUri, fs, buffers = new Map()) {
+    let pending;
+    return {
+        rootUri,
+        fs,
+        sources: () => (pending ??= readEdgeSources(rootUri, fs, buffers)),
+    };
+}
+async function readEdgeSources(rootUri, fs, buffers) {
+    const uris = await enumerateEdgeSources(fs, rootUri);
+    const sources = new Map();
+    await Promise.all(uris.map(async (uri) => {
+        const key = path.normalize(uri);
+        // The buffer is the truth for this file; reading it would race the overlay below.
+        if (buffers.has(key))
+            return;
+        // A file that vanished between the walk and the read cannot be a dependent, and
+        // failing the whole scan over it would cost the answer for every other file.
+        const source = await fs.readFile(uri).catch(() => undefined);
+        if (source !== undefined)
+            sources.set(key, source);
+    }));
+    for (const [uri, source] of buffers) {
+        // A buffer that is not an edge source (a `.graphql` operation, a schema `.yml`)
+        // declares no outgoing edges, so it can only be a target — nothing to scan.
+        if (isEdgeSource(uri, rootUri))
+            sources.set(uri, source);
+    }
+    return sources;
+}
+//# sourceMappingURL=project-scan.js.map

package/dist/impact/project-scan.spec.d.ts

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

package/dist/impact/project-scan.spec.js

@@ -0,0 +1,121 @@
+import { describe, expect, it } from 'vitest';
+import { FileType } from '@platformos/platformos-common';
+import { createProjectScan } from './project-scan.js';
+const ROOT = 'file:///project';
+/**
+ * A filesystem over a `relative path → contents` tree that COUNTS its reads, which
+ * is the whole point: the scan's contract is what it costs, not just what it
+ * returns.
+ */
+function countingFs(tree) {
+    const reads = [];
+    const paths = Object.keys(tree);
+    const fs = {
+        async readFile(uri) {
+            reads.push(uri);
+            const contents = tree[uri.slice(`${ROOT}/`.length)];
+            if (contents === undefined)
+                throw new Error(`no such file: ${uri}`);
+            return contents;
+        },
+        async readDirectory(uri) {
+            const prefix = uri === ROOT ? '' : `${uri.slice(`${ROOT}/`.length)}/`;
+            const entries = new Map();
+            for (const filePath of paths) {
+                if (!filePath.startsWith(prefix))
+                    continue;
+                const rest = filePath.slice(prefix.length);
+                const cut = rest.indexOf('/');
+                entries.set(cut === -1 ? rest : rest.slice(0, cut), cut === -1 ? FileType.File : FileType.Directory);
+            }
+            if (entries.size === 0)
+                throw new Error(`no such directory: ${uri}`);
+            return [...entries].map(([name, type]) => [`${uri}/${name}`, type]);
+        },
+        async stat(uri) {
+            const contents = tree[uri.slice(`${ROOT}/`.length)];
+            if (contents === undefined)
+                throw new Error(`no such file: ${uri}`);
+            return { type: FileType.File, size: contents.length };
+        },
+    };
+    return { fs, reads };
+}
+const PROJECT = {
+    'app/views/pages/index.liquid': "{% render 'card' %}",
+    'app/views/partials/card.liquid': '<div></div>',
+    'app/graphql/get_posts.graphql': 'query { posts { id } }',
+};
+describe('createProjectScan', () => {
+    it('reads every edge source, and nothing that cannot declare an edge', async () => {
+        const { fs } = countingFs(PROJECT);
+        const sources = await createProjectScan(ROOT, fs).sources();
+        // The `.graphql` operation is a LEAF: it can be referenced but can never
+        // reference, so reading it would be pure cost.
+        expect([...sources.keys()].sort()).toEqual([
+            'file:///project/app/views/pages/index.liquid',
+            'file:///project/app/views/partials/card.liquid',
+        ]);
+    });
+    it('reads the project ONCE however many times it is asked', async () => {
+        const { fs, reads } = countingFs(PROJECT);
+        const scan = createProjectScan(ROOT, fs);
+        const [first, second, third] = await Promise.all([
+            scan.sources(),
+            scan.sources(),
+            scan.sources(),
+        ]);
+        // Same object back, and two liquid files read in total — not six.
+        expect([first === second, second === third]).toEqual([true, true]);
+        expect(reads.sort()).toEqual([
+            'file:///project/app/views/pages/index.liquid',
+            'file:///project/app/views/partials/card.liquid',
+        ]);
+    });
+    it('reads nothing at all until it is asked', async () => {
+        const { fs, reads } = countingFs(PROJECT);
+        createProjectScan(ROOT, fs);
+        expect(reads).toEqual([]);
+    });
+    it('serves a buffer instead of the file on disk, without reading that file', async () => {
+        const { fs, reads } = countingFs(PROJECT);
+        const page = 'file:///project/app/views/pages/index.liquid';
+        const sources = await createProjectScan(ROOT, fs, new Map([[page, "{% render 'other' %}"]])).sources();
+        expect(sources.get(page)).toEqual("{% render 'other' %}");
+        expect(reads).toEqual(['file:///project/app/views/partials/card.liquid']);
+    });
+    it('includes a buffer for a file that is not on disk yet', async () => {
+        const { fs } = countingFs(PROJECT);
+        const fresh = 'file:///project/app/views/pages/brand-new.liquid';
+        const sources = await createProjectScan(ROOT, fs, new Map([[fresh, "{% render 'card' %}"]]))
+            .sources()
+            .then((all) => all);
+        expect(sources.get(fresh)).toEqual("{% render 'card' %}");
+    });
+    it('drops a buffer that could never declare an edge, rather than scanning it', async () => {
+        const { fs } = countingFs(PROJECT);
+        const operation = 'file:///project/app/graphql/get_posts.graphql';
+        const sources = await createProjectScan(ROOT, fs, new Map([[operation, 'query { posts { id title } }']])).sources();
+        expect(sources.has(operation)).toBe(false);
+    });
+    /**
+     * A file the walk saw and the read could not open is the ordinary race (it was
+     * deleted in between), not a reason to lose the whole answer.
+     *
+     * The control is `index.liquid`: the same scan still returns it, so "card is
+     * missing" cannot be the scan having failed wholesale.
+     */
+    it('skips a file that vanished between the walk and the read, keeping the rest', async () => {
+        const { fs } = countingFs(PROJECT);
+        const vanishing = 'file:///project/app/views/partials/card.liquid';
+        const readFile = fs.readFile.bind(fs);
+        fs.readFile = async (uri) => {
+            if (uri === vanishing)
+                throw new Error('ENOENT');
+            return readFile(uri);
+        };
+        const sources = await createProjectScan(ROOT, fs).sources();
+        expect([...sources.keys()]).toEqual(['file:///project/app/views/pages/index.liquid']);
+    });
+});
+//# sourceMappingURL=project-scan.spec.js.map

package/dist/index.d.ts

@@ -2,7 +2,7 @@
 export { startServer } from './transport/server.js';
 export type { ServerOptions, ServerHandle } from './transport/server.js';
 export { registerValidateCode, VALIDATE_CODE_INPUT } from './transport/validate-code.js';
-export type { SupervisorContext } from './transport/validate-code.js';
+export type { SupervisorContext } from './context.js';
 export { createLogger } from './logger.js';
 export type { Logger } from './logger.js';
 export * from './result/types.js';

package/dist/lint/fixes.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The engine's concrete edits, in the shape an agent applies them in.
+ *
+ * A PURE SHAPE MAPPING and nothing more. `check-node` runs the `Fixer` functions — beside
+ * the lint, while the `App` still holds the buffer — and hands back `FixDescription[]`; all
+ * that is left here is renaming three fields.
+ *
+ * RUNNING A FIXER HERE WOULD BE WRONG: a fixer may read back through the `App`
+ * (`missing-doc-param`'s calls `indentationOfLineAt`, which reads `file.source`), and after
+ * `lintBuffers` has reverted its overlay that either throws or computes against DISK text.
+ *
+ * NOTHING HERE AUTHORS EDIT TEXT. Every byte came out of a corrector a check drove.
+ */
+import type { MaterialisedFix } from '@platformos/platformos-check-node';
+import type { AgentFix } from '../result/types.js';
+/** The agent-facing fix fields for one offense; keys are absent when the engine offered none. */
+export interface OffenseFixes {
+    fix?: AgentFix;
+    suggestions?: AgentFix[];
+}
+/**
+ * Map one offense's materialised fixes onto the diagnostic shape.
+ *
+ * `fix` and `suggestions` stay separate because the engine draws that distinction and an
+ * agent must act on it differently: a fix is the answer and is safe to apply unread, a
+ * suggestion is one of several choices and carries the engine's own wording.
+ */
+export declare function toAgentFixes(materialised: MaterialisedFix | undefined): OffenseFixes;

package/dist/lint/fixes.js

@@ -0,0 +1,30 @@
+/** check-common's `FixDescription` → the agent's `AgentEdit`. Field names, nothing else. */
+function toEdits(edits) {
+    return edits.map((edit) => ({
+        start_index: edit.startIndex,
+        end_index: edit.endIndex,
+        new_text: edit.insert,
+    }));
+}
+/**
+ * Map one offense's materialised fixes onto the diagnostic shape.
+ *
+ * `fix` and `suggestions` stay separate because the engine draws that distinction and an
+ * agent must act on it differently: a fix is the answer and is safe to apply unread, a
+ * suggestion is one of several choices and carries the engine's own wording.
+ */
+export function toAgentFixes(materialised) {
+    if (!materialised)
+        return {};
+    const result = {};
+    if (materialised.fix)
+        result.fix = { edits: toEdits(materialised.fix) };
+    if (materialised.suggestions) {
+        result.suggestions = materialised.suggestions.map((suggestion) => ({
+            description: suggestion.message,
+            edits: toEdits(suggestion.edits),
+        }));
+    }
+    return result;
+}
+//# sourceMappingURL=fixes.js.map