@platformos/platformos-check-node 0.0.19 → 0.0.20

package/README.md

@@ -4,6 +4,48 @@ This is the Node.js wrapper of the runtime-agnostic [`@platformos/platformos-che
 
 See the [@platformos/platformos-check-common README](../platformos-check-common) for more details.
 
+## Entrypoints
+
+| Function | Use |
+|---|---|
+| `check(root, configPath?)` | Lint a whole project on disk; returns `Offense[]`. |
+| `appCheckRun(root, configPath?, log?)` | Same, but also returns the resolved `App` and `Config`. |
+| `checkAndAutofix(root, configPath?)` | Lint then apply safe autofixes to disk. |
+| `lintBuffer(params)` | Lint a single in-memory buffer in the context of its on-disk project. |
+
+### `lintBuffer` — lint one buffer with project overlay
+
+`lintBuffer` is the typed seam an embedding tool (e.g. the MCP supervisor) lints
+through — a **direct library call, not an LSP and not a subprocess**. It loads
+the project from disk so cross-file checks (`MissingPartial`, `MissingPage`,
+`OrphanedPartial`, …) resolve against real files, overlays the buffer under edit
+in memory so the **unsaved** content is what gets linted and cross-referenced,
+and returns the structured check-common `Offense[]` for that file with `fix` /
+`suggest` and every typed field intact — no message-string round-trip.
+
+```ts
+import { lintBuffer } from '@platformos/platformos-check-node';
+
+const offenses = await lintBuffer({
+  root: '/abs/path/to/project',                 // project root (absolute)
+  filePath: '/abs/path/to/project/app/views/pages/contact.liquid', // file under edit (absolute)
+  content: editorBufferContents,                // unsaved buffer
+  // configPath?: explicit config; resolved from root when omitted
+});
+
+for (const offense of offenses) {
+  offense.check;     // e.g. 'MissingPartial'
+  offense.severity;  // Severity
+  offense.start.index; offense.end.index; // 0-based offsets
+  offense.fix;       // optional Fixer (safe autofix)
+  offense.suggest;   // optional Suggestion[] (manual fixes)
+}
+```
+
+When `filePath` already exists in the project its on-disk source is replaced by
+the buffer; when it is new (not yet saved) the buffer is added so it is still
+linted. Only offenses for the buffer's file are returned.
+
 ## License
 
 MIT.

package/configs/all.yml

@@ -42,6 +42,9 @@ MatchingTranslations:
 MissingAsset:
   enabled: true
   severity: 0
+MissingContentForLayout:
+  enabled: true
+  severity: 0
 MissingPage:
   enabled: true
   severity: 1
@@ -64,6 +67,9 @@ ParserBlockingScript:
 PartialCallArguments:
   enabled: true
   severity: 0
+ReservedVariableName:
+  enabled: true
+  severity: 0
 TranslationKeyExists:
   enabled: true
   severity: 0

package/configs/recommended.yml

@@ -42,6 +42,9 @@ MatchingTranslations:
 MissingAsset:
   enabled: true
   severity: 0
+MissingContentForLayout:
+  enabled: true
+  severity: 0
 MissingPage:
   enabled: true
   severity: 1
@@ -64,6 +67,9 @@ ParserBlockingScript:
 PartialCallArguments:
   enabled: true
   severity: 0
+ReservedVariableName:
+  enabled: true
+  severity: 0
 TranslationKeyExists:
   enabled: true
   severity: 0

package/dist/index.d.ts

@@ -16,6 +16,33 @@ export declare function toSourceCode(absolutePath: string): Promise<LiquidSource
 export declare function check(root: string, configPath?: string): Promise<Offense[]>;
 export declare function checkAndAutofix(root: string, configPath?: string): Promise<void>;
 export declare function appCheckRun(root: string, configPath?: string, log?: (message: string) => void): Promise<AppCheckRun>;
+export interface LintBufferParams {
+    /** Absolute path to the project root. */
+    root: string;
+    /** Absolute path to the file under edit. */
+    filePath: string;
+    /** In-memory contents of the file under edit (may differ from, or not yet exist on, disk). */
+    content: string;
+    /** Explicit config path; resolved from `root` when omitted. */
+    configPath?: string;
+    log?: (message: string) => void;
+}
+/**
+ * Lint a single in-memory buffer in the context of its on-disk project.
+ *
+ * This is the typed seam the MCP supervisor lints through — NOT an LSP, NOT a
+ * subprocess. The on-disk project is loaded so cross-file checks
+ * (`MissingPartial`, `MissingPage`, `OrphanedPartial`, …) resolve against real
+ * files, and the buffer under edit is overlaid in memory so the UNSAVED content
+ * is what gets linted and cross-referenced. Returns the structured
+ * check-common `Offense[]` for the buffer's file, with `fix` / `suggest` and all
+ * typed fields preserved end to end (no message-string round-trip).
+ *
+ * `filePath` must be absolute. When it already exists in the project its
+ * on-disk `SourceCode` is replaced by the buffer; when it is new (not yet
+ * saved) the buffer is added so it is still linted.
+ */
+export declare function lintBuffer(params: LintBufferParams): Promise<Offense[]>;
 export declare function getAppAndConfig(root: string, configPath?: string): Promise<{
     app: App;
     config: Config;

package/dist/index.js

@@ -23,6 +23,7 @@ exports.toSourceCode = toSourceCode;
 exports.check = check;
 exports.checkAndAutofix = checkAndAutofix;
 exports.appCheckRun = appCheckRun;
+exports.lintBuffer = lintBuffer;
 exports.getAppAndConfig = getAppAndConfig;
 exports.getApp = getApp;
 exports.getAppFilesPathPattern = getAppFilesPathPattern;
@@ -70,6 +71,24 @@ async function checkAndAutofix(root, configPath) {
 }
 async function appCheckRun(root, configPath, log = () => { }) {
     const { app, config } = await getAppAndConfig(root, configPath);
+    const offenses = await lintApp(root, app, config, log);
+    return {
+        app,
+        config,
+        offenses,
+    };
+}
+/**
+ * Run the configured checks over an in-memory `App` and return the structured
+ * `Offense[]` (with `fix` / `suggest` and all typed fields intact).
+ *
+ * Shared by {@link appCheckRun} (whole project on disk) and
+ * {@link lintBuffer} (project on disk + one buffer overlaid). Building the
+ * `getDocDefinition` map from the passed `app` is what lets the overlaid buffer
+ * be cross-referenced with its UNSAVED `{% doc %}` params rather than the
+ * stale on-disk version.
+ */
+async function lintApp(root, app, config, log = () => { }) {
     const platformOSLiquidDocsManager = new platformos_check_docs_updater_1.PlatformOSLiquidDocsManager(log);
     const validator = await platformos_check_common_1.JSONValidator.create(platformOSLiquidDocsManager, config);
     const docDefinitions = new Map(app.map((file) => [
@@ -85,17 +104,52 @@ async function appCheckRun(root, configPath, log = () => { }) {
             return (0, platformos_check_common_1.extractDocDefinition)(file.uri, ast);
         }),
     ]));
-    const offenses = await (0, platformos_check_common_1.check)(app, config, {
+    return (0, platformos_check_common_1.check)(app, config, {
         fs: NodeFileSystem_1.NodeFileSystem,
         platformosDocset: platformOSLiquidDocsManager,
         jsonValidationSet: platformOSLiquidDocsManager,
         getDocDefinition: async (relativePath) => docDefinitions.get(relativePath)?.(),
     });
-    return {
-        app,
-        config,
-        offenses,
-    };
+}
+/**
+ * Lint a single in-memory buffer in the context of its on-disk project.
+ *
+ * This is the typed seam the MCP supervisor lints through — NOT an LSP, NOT a
+ * subprocess. The on-disk project is loaded so cross-file checks
+ * (`MissingPartial`, `MissingPage`, `OrphanedPartial`, …) resolve against real
+ * files, and the buffer under edit is overlaid in memory so the UNSAVED content
+ * is what gets linted and cross-referenced. Returns the structured
+ * check-common `Offense[]` for the buffer's file, with `fix` / `suggest` and all
+ * typed fields preserved end to end (no message-string round-trip).
+ *
+ * `filePath` must be absolute. When it already exists in the project its
+ * on-disk `SourceCode` is replaced by the buffer; when it is new (not yet
+ * saved) the buffer is added so it is still linted.
+ */
+async function lintBuffer(params) {
+    const { root, filePath, content, configPath, log = () => { } } = params;
+    const { app, config } = await getAppAndConfig(root, configPath);
+    const uri = platformos_check_common_1.path.normalize(vscode_uri_1.URI.file(filePath));
+    const overlaidApp = overlayBuffer(app, uri, content);
+    const offenses = await lintApp(root, overlaidApp, config, log);
+    return offenses.filter((offense) => offense.uri === uri);
+}
+/**
+ * Return a copy of `app` with the `SourceCode` for `uri` replaced by one built
+ * from `content`, appending it when the file is not already present.
+ */
+function overlayBuffer(app, uri, content) {
+    const overlay = (0, platformos_check_common_1.toSourceCode)(uri, content);
+    let replaced = false;
+    const next = app.map((file) => {
+        if (file.uri !== uri)
+            return file;
+        replaced = true;
+        return overlay;
+    });
+    if (!replaced)
+        next.push(overlay);
+    return next;
 }
 async function getAppAndConfig(root, configPath) {
     const config = await (0, exports.loadConfig)(configPath, root);
@@ -127,13 +181,20 @@ async function getApp(config) {
         // Schema files, generator templates (e.g. ERB .graphql), etc. are excluded.
         if (filePath.endsWith('.graphql') && !(0, platformos_check_common_1.isKnownGraphQLFile)(filePath))
             return false;
+        // Only lint .yml/.yaml files that belong to a recognized platformOS YAML
+        // directory (translations, custom model types, etc.). Config files like
+        // config.yml or .platformos-check.yml are excluded.
+        if ((filePath.endsWith('.yml') || filePath.endsWith('.yaml')) &&
+            !(0, platformos_check_common_1.isKnownYAMLFile)(filePath)) {
+            return false;
+        }
         return true;
     }));
     const sourceCodes = await Promise.all(paths.map(toSourceCode));
     return sourceCodes.filter((x) => x !== undefined);
 }
 function getAppFilesPathPattern(rootUri) {
-    return (0, normalize_path_1.default)(node_path_1.default.join((0, node_url_1.fileURLToPath)(rootUri), '**/*.{liquid,json,graphql,yml,yaml}'));
+    return (0, normalize_path_1.default)(node_path_1.default.join((0, node_url_1.fileURLToPath)(rootUri), '**/*.{liquid,graphql,yml,yaml}'));
 }
 /** @deprecated Use appCheckRun instead */
 exports.runCheck = appCheckRun;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@platformos/platformos-check-node",
-  "version": "0.0.19",
+  "version": "0.0.20",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "author": "platformOS",
@@ -33,8 +33,8 @@
     "type-check": "tsc --noEmit"
   },
   "dependencies": {
-    "@platformos/platformos-check-common": "0.0.19",
-    "@platformos/platformos-check-docs-updater": "0.0.19",
+    "@platformos/platformos-check-common": "0.0.20",
+    "@platformos/platformos-check-docs-updater": "0.0.20",
     "glob": "^13.0.0",
     "normalize-path": "^3.0.0",
     "vscode-uri": "^3.1.0",