@quenty/nevermore-cli 4.18.0 → 4.19.0

package/dist/utils/testing/parsers/roblox-path-resolver.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"roblox-path-resolver.test.d.ts","sourceRoot":"","sources":["../../../../src/utils/testing/parsers/roblox-path-resolver.test.ts"],"names":[],"mappings":""}

package/dist/utils/testing/parsers/roblox-path-resolver.test.js

@@ -0,0 +1,76 @@
+import { describe, it, expect } from 'vitest';
+import { resolveRobloxTestPath } from './roblox-path-resolver.js';
+import { SourcemapResolver } from '../../sourcemap/index.js';
+describe('resolveRobloxTestPath', () => {
+    it('resolves a standard ServerScriptService path', () => {
+        expect(resolveRobloxTestPath('ServerScriptService.observablecollection.Shared.ObservableList.spec')).toBe('src/observablecollection/src/Shared/ObservableList.spec.lua');
+    });
+    it('resolves a nested subdirectory path', () => {
+        expect(resolveRobloxTestPath('ServerScriptService.maid.Shared.Maid.spec')).toBe('src/maid/src/Shared/Maid.spec.lua');
+    });
+    it('resolves a deeply nested path', () => {
+        expect(resolveRobloxTestPath('ServerScriptService.blend.Client.Blend.Spring.SpringObject.spec')).toBe('src/blend/src/Client/Blend/Spring/SpringObject.spec.lua');
+    });
+    it('handles missing ServerScriptService prefix as fallback', () => {
+        expect(resolveRobloxTestPath('observablecollection.Shared.ObservableList.spec')).toBe('src/observablecollection/src/Shared/ObservableList.spec.lua');
+    });
+    it('strips :LINE suffix', () => {
+        expect(resolveRobloxTestPath('ServerScriptService.observablecollection.Shared.ObservableList.spec:45')).toBe('src/observablecollection/src/Shared/ObservableList.spec.lua');
+    });
+    it('handles path without ServerScriptService prefix and with :LINE suffix', () => {
+        expect(resolveRobloxTestPath('maid.Shared.Maid.spec:23')).toBe('src/maid/src/Shared/Maid.spec.lua');
+    });
+    it('handles a bare package slug', () => {
+        expect(resolveRobloxTestPath('ServerScriptService.maid')).toBe('src/maid/src');
+    });
+    it('handles a single-level spec path', () => {
+        expect(resolveRobloxTestPath('ServerScriptService.maid.Maid.spec')).toBe('src/maid/src/Maid.spec.lua');
+    });
+    describe('with sourcemap resolver', () => {
+        const repoRoot = '/repo';
+        const sourcemap = {
+            name: 'Nevermore',
+            className: 'DataModel',
+            children: [
+                {
+                    name: 'mypkg',
+                    className: 'Folder',
+                    filePaths: [`${repoRoot}/src/mypkg/default.project.json`],
+                    children: [
+                        {
+                            name: 'Shared',
+                            className: 'Folder',
+                            children: [
+                                {
+                                    name: 'MyModule',
+                                    className: 'ModuleScript',
+                                    filePaths: [`${repoRoot}/src/mypkg/src/Shared/MyModule.lua`],
+                                    children: [
+                                        {
+                                            name: 'MyModule.spec',
+                                            className: 'ModuleScript',
+                                            filePaths: [
+                                                `${repoRoot}/src/mypkg/src/Shared/MyModule.spec.lua`,
+                                            ],
+                                        },
+                                    ],
+                                },
+                            ],
+                        },
+                    ],
+                },
+            ],
+        };
+        const resolver = SourcemapResolver.fromSourcemap(sourcemap, repoRoot);
+        it('uses sourcemap when path is found', () => {
+            expect(resolveRobloxTestPath('ServerScriptService.mypkg.Shared.MyModule.MyModule.spec', resolver)).toBe('src/mypkg/src/Shared/MyModule.spec.lua');
+        });
+        it('falls back to heuristic when sourcemap has no mapping', () => {
+            expect(resolveRobloxTestPath('ServerScriptService.unknownpkg.Shared.Foo.spec', resolver)).toBe('src/unknownpkg/src/Shared/Foo.spec.lua');
+        });
+        it('strips :LINE suffix with sourcemap', () => {
+            expect(resolveRobloxTestPath('ServerScriptService.mypkg.Shared.MyModule.MyModule.spec:42', resolver)).toBe('src/mypkg/src/Shared/MyModule.spec.lua');
+        });
+    });
+});
+//# sourceMappingURL=roblox-path-resolver.test.js.map

package/dist/utils/testing/parsers/roblox-path-resolver.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"roblox-path-resolver.test.js","sourceRoot":"","sources":["../../../../src/utils/testing/parsers/roblox-path-resolver.test.ts"],"names":[],"mappings":"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"}

package/dist/utils/testing/test-log-parser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"test-log-parser.d.ts","sourceRoot":"","sources":["../../../src/utils/testing/test-log-parser.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,CAiB/D"}
+{"version":3,"file":"test-log-parser.d.ts","sourceRoot":"","sources":["../../../src/utils/testing/test-log-parser.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,CAiB/D"}

package/dist/utils/testing/test-log-parser.js

@@ -1,9 +1,10 @@
+import { OutputHelper } from '@quenty/cli-output-helpers';
 /**
  * Analyze test output for Jest failures and Luau runtime errors.
  * Shared by both Open Cloud log fetching and local run-in-roblox output.
  */
 export function parseTestLogs(rawOutput) {
-    const cleanLogs = rawOutput.replace(/\x1b\[[0-9;]*[a-zA-Z]/g, '');
+    const cleanLogs = OutputHelper.stripAnsi(rawOutput);
     // Check for Jest-style test failures
     const failedSuites = cleanLogs.match(/Test Suites:\s*(\d+)\s+failed/);
     const failedTests = cleanLogs.match(/Tests:\s*(\d+)\s+failed/);

package/dist/utils/testing/test-log-parser.js.map

@@ -1 +1 @@
-{"version":3,"file":"test-log-parser.js","sourceRoot":"","sources":["../../../src/utils/testing/test-log-parser.ts"],"names":[],"mappings":"AAKA;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,SAAiB;IAC7C,MAAM,SAAS,GAAG,SAAS,CAAC,OAAO,CAAC,wBAAwB,EAAE,EAAE,CAAC,CAAC;IAElE,qCAAqC;IACrC,MAAM,YAAY,GAAG,SAAS,CAAC,KAAK,CAAC,+BAA+B,CAAC,CAAC;IACtE,MAAM,WAAW,GAAG,SAAS,CAAC,KAAK,CAAC,yBAAyB,CAAC,CAAC;IAC/D,MAAM,eAAe,GACnB,CAAC,YAAY,IAAI,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC;QACnD,CAAC,WAAW,IAAI,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAEpD,+CAA+C;IAC/C,MAAM,eAAe,GAAG,eAAe,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAExD,OAAO;QACL,OAAO,EAAE,CAAC,eAAe,IAAI,CAAC,eAAe;QAC7C,IAAI,EAAE,SAAS;KAChB,CAAC;AACJ,CAAC"}
+{"version":3,"file":"test-log-parser.js","sourceRoot":"","sources":["../../../src/utils/testing/test-log-parser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAO1D;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,SAAiB;IAC7C,MAAM,SAAS,GAAG,YAAY,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;IAEpD,qCAAqC;IACrC,MAAM,YAAY,GAAG,SAAS,CAAC,KAAK,CAAC,+BAA+B,CAAC,CAAC;IACtE,MAAM,WAAW,GAAG,SAAS,CAAC,KAAK,CAAC,yBAAyB,CAAC,CAAC;IAC/D,MAAM,eAAe,GACnB,CAAC,YAAY,IAAI,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC;QACnD,CAAC,WAAW,IAAI,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAEpD,+CAA+C;IAC/C,MAAM,eAAe,GAAG,eAAe,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAExD,OAAO;QACL,OAAO,EAAE,CAAC,eAAe,IAAI,CAAC,eAAe;QAC7C,IAAI,EAAE,SAAS;KAChB,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/nevermore-cli",
-  "version": "4.18.0",
+  "version": "4.19.0",
   "description": "CLI interface for Nevermore",
   "type": "module",
   "keywords": [
@@ -25,10 +25,10 @@
     "Quenty"
   ],
   "dependencies": {
-    "@quenty/cli-output-helpers": "1.7.0",
-    "@quenty/nevermore-cli-helpers": "1.5.0",
-    "@quenty/nevermore-template-helpers": "1.8.0",
-    "@quenty/studio-bridge": "0.4.0",
+    "@quenty/cli-output-helpers": "1.8.0",
+    "@quenty/nevermore-cli-helpers": "1.6.0",
+    "@quenty/nevermore-template-helpers": "1.9.0",
+    "@quenty/studio-bridge": "0.5.0",
     "execa": "^9.6.1",
     "find-git-root": "^1.0.4",
     "inquirer": "^13.2.0",
@@ -57,5 +57,5 @@
   "engines": {
     "node": ">=16"
   },
-  "gitHead": "e283e4923e6b052d9b4db9a29f012b91e7a3440c"
+  "gitHead": "3e227cd352996f0ee771361ca5140ce7e366de00"
 }

package/src/commands/tools-command/ci-post-test-results.ts

@@ -1,5 +1,10 @@
 import { CommandModule } from 'yargs';
 import { OutputHelper } from '@quenty/cli-output-helpers';
+import {
+  type Diagnostic,
+  emitAnnotations,
+  writeAnnotationSummaryAsync,
+} from '@quenty/cli-output-helpers/reporting';
 import { NevermoreGlobalArgs } from '../../args/global-args.js';
 import {
   type IStateTracker,
@@ -9,6 +14,8 @@ import {
   LoadedStateTracker,
   createTestCommentConfig,
 } from '../../utils/testing/reporting/index.js';
+import { parseJestLuaOutput } from '../../utils/testing/parsers/index.js';
+import { tryLoadSourcemapResolver } from '../../utils/sourcemap/index.js';
 
 type ErrorReporter = Reporter & {
   setError(error: string): void;
@@ -86,6 +93,25 @@ export const ciPostTestResultsCommand: CommandModule<
         return;
       }
 
+      // Emit test failure annotations
+      const sourcemapResolver = tryLoadSourcemapResolver(process.cwd());
+      const allDiagnostics: Diagnostic[] = [];
+      for (const failure of state.getFailures()) {
+        const diagnostics = parseJestLuaOutput(failure.logs, {
+          packageName: failure.packageName,
+          sourcemapResolver,
+        });
+        allDiagnostics.push(...diagnostics);
+      }
+
+      if (allDiagnostics.length > 0) {
+        OutputHelper.info(
+          `Found ${allDiagnostics.length} test failure(s). Emitting annotations...`
+        );
+        emitAnnotations(allDiagnostics);
+        await writeAnnotationSummaryAsync('Test Failures', allDiagnostics);
+      }
+
       const reporters = _createGithubReporters(state, 1);
       for (const r of reporters) {
         await r.stopAsync();

package/src/commands/tools-command/strip-sourcemap-jest-command.ts

@@ -3,13 +3,7 @@ import * as path from 'path';
 import { CommandModule } from 'yargs';
 import { OutputHelper } from '@quenty/cli-output-helpers';
 import { NevermoreGlobalArgs } from '../../args/global-args.js';
-
-interface SourcemapNode {
-  name: string;
-  className?: string;
-  children?: SourcemapNode[];
-  filePaths?: string[];
-}
+import type { SourcemapNode } from '../../utils/sourcemap/index.js';
 
 interface StripSourcemapJestArgs extends NevermoreGlobalArgs {
   sourcemap?: string;

package/src/utils/linting/parsers/moonwave-parser.ts

@@ -21,18 +21,13 @@
  */
 
 import { type Diagnostic, type DiagnosticSeverity } from '@quenty/cli-output-helpers/reporting';
+import { OutputHelper } from '@quenty/cli-output-helpers';
 import {
   LERNA_PREFIX_PATTERN,
   LERNA_PREFIX_PATTERN_NC,
   resolvePackagePath,
 } from './lerna-utils.js';
 
-/** Strip all ANSI escape sequences from a string. */
-const ANSI_PATTERN = /\x1b\[[0-9;]*m/g;
-function _stripAnsi(text: string): string {
-  return text.replace(ANSI_PATTERN, '');
-}
-
 /**
  * Matches the severity header line.
  * Optional lerna prefix (captures package name).
@@ -64,7 +59,7 @@ export function parseMoonwaveOutput(raw: string): Diagnostic[] {
   let pending: PendingDiagnostic | undefined;
 
   for (const rawLine of lines) {
-    const line = _stripAnsi(rawLine);
+    const line = OutputHelper.stripAnsi(rawLine);
 
     // Skip the "aborting due to diagnostic error" summary line
     if (line.includes('aborting due to')) continue;

package/src/utils/sourcemap/index.ts

@@ -0,0 +1,3 @@
+export type { SourcemapNode } from './sourcemap-types.js';
+export { SourcemapResolver } from './sourcemap-resolver.js';
+export { tryLoadSourcemapResolver } from './sourcemap-loader.js';

package/src/utils/sourcemap/sourcemap-loader.ts

@@ -0,0 +1,33 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import type { SourcemapNode } from './sourcemap-types.js';
+import { SourcemapResolver } from './sourcemap-resolver.js';
+
+/**
+ * Try to load a `SourcemapResolver` from `sourcemap.json` in the given
+ * directory.
+ *
+ * Returns `undefined` if the file doesn't exist or can't be parsed — callers
+ * should fall back to heuristic resolution.
+ */
+export function tryLoadSourcemapResolver(
+  repoRoot: string
+): SourcemapResolver | undefined {
+  const sourcemapPath = path.join(repoRoot, 'sourcemap.json');
+
+  let content: string;
+  try {
+    content = fs.readFileSync(sourcemapPath, 'utf-8');
+  } catch {
+    return undefined;
+  }
+
+  let root: SourcemapNode;
+  try {
+    root = JSON.parse(content) as SourcemapNode;
+  } catch {
+    return undefined;
+  }
+
+  return SourcemapResolver.fromSourcemap(root, repoRoot);
+}

package/src/utils/sourcemap/sourcemap-resolver.test.ts

@@ -0,0 +1,150 @@
+import { describe, it, expect } from 'vitest';
+import { SourcemapResolver } from './sourcemap-resolver.js';
+import type { SourcemapNode } from './sourcemap-types.js';
+
+/**
+ * Minimal sourcemap tree that mirrors a typical Nevermore project:
+ *
+ *   Nevermore (root)
+ *     └─ observablecollection
+ *          └─ Shared
+ *               └─ ObservableList
+ *                    └─ ObservableList.spec
+ */
+function _createTestSourcemap(repoRoot: string): SourcemapNode {
+  return {
+    name: 'Nevermore',
+    className: 'DataModel',
+    children: [
+      {
+        name: 'observablecollection',
+        className: 'Folder',
+        filePaths: [`${repoRoot}/src/observablecollection/default.project.json`],
+        children: [
+          {
+            name: 'Shared',
+            className: 'Folder',
+            children: [
+              {
+                name: 'ObservableList',
+                className: 'ModuleScript',
+                filePaths: [
+                  `${repoRoot}/src/observablecollection/src/Shared/ObservableList.lua`,
+                ],
+                children: [
+                  {
+                    name: 'ObservableList.spec',
+                    className: 'ModuleScript',
+                    filePaths: [
+                      `${repoRoot}/src/observablecollection/src/Shared/ObservableList.spec.lua`,
+                    ],
+                  },
+                ],
+              },
+            ],
+          },
+        ],
+      },
+      {
+        name: 'maid',
+        className: 'Folder',
+        filePaths: [`${repoRoot}/src/maid/default.project.json`],
+        children: [
+          {
+            name: 'Shared',
+            className: 'Folder',
+            children: [
+              {
+                name: 'Maid',
+                className: 'ModuleScript',
+                filePaths: [`${repoRoot}/src/maid/src/Shared/Maid.lua`],
+                children: [
+                  {
+                    name: 'Maid.spec',
+                    className: 'ModuleScript',
+                    filePaths: [
+                      `${repoRoot}/src/maid/src/Shared/Maid.spec.lua`,
+                    ],
+                  },
+                ],
+              },
+            ],
+          },
+        ],
+      },
+    ],
+  };
+}
+
+describe('SourcemapResolver', () => {
+  const repoRoot = '/repo';
+  const resolver = SourcemapResolver.fromSourcemap(
+    _createTestSourcemap(repoRoot),
+    repoRoot
+  );
+
+  it('resolves a spec file instance path', () => {
+    expect(
+      resolver.resolve(
+        'ServerScriptService.observablecollection.Shared.ObservableList.ObservableList.spec'
+      )
+    ).toBe('src/observablecollection/src/Shared/ObservableList.spec.lua');
+  });
+
+  it('resolves a module instance path', () => {
+    expect(
+      resolver.resolve(
+        'ServerScriptService.observablecollection.Shared.ObservableList'
+      )
+    ).toBe('src/observablecollection/src/Shared/ObservableList.lua');
+  });
+
+  it('strips :LINE suffix before lookup', () => {
+    expect(
+      resolver.resolve(
+        'ServerScriptService.maid.Shared.Maid.Maid.spec:23'
+      )
+    ).toBe('src/maid/src/Shared/Maid.spec.lua');
+  });
+
+  it('returns undefined for unknown paths', () => {
+    expect(
+      resolver.resolve('ServerScriptService.nonexistent.Shared.Foo')
+    ).toBeUndefined();
+  });
+
+  it('skips nodes that only have .project.json (no lua files)', () => {
+    // The "observablecollection" folder node only has a .project.json filePath.
+    // It should not be indexed.
+    expect(
+      resolver.resolve('ServerScriptService.observablecollection')
+    ).toBeUndefined();
+  });
+
+  it('resolves paths in a different package', () => {
+    expect(
+      resolver.resolve('ServerScriptService.maid.Shared.Maid')
+    ).toBe('src/maid/src/Shared/Maid.lua');
+  });
+
+  it('supports a custom root alias', () => {
+    const customResolver = SourcemapResolver.fromSourcemap(
+      _createTestSourcemap(repoRoot),
+      repoRoot,
+      'ReplicatedStorage'
+    );
+
+    expect(
+      customResolver.resolve(
+        'ReplicatedStorage.maid.Shared.Maid'
+      )
+    ).toBe('src/maid/src/Shared/Maid.lua');
+
+    // ServerScriptService should NOT work with a different alias
+    expect(
+      customResolver.resolve(
+        'ServerScriptService.maid.Shared.Maid'
+      )
+    ).toBeUndefined();
+  });
+});

package/src/utils/sourcemap/sourcemap-resolver.ts

@@ -0,0 +1,75 @@
+import * as path from 'path';
+import type { SourcemapNode } from './sourcemap-types.js';
+
+/**
+ * Builds a lookup index from a Rojo sourcemap tree so that dotted Roblox
+ * instance paths (e.g. `ServerScriptService.maid.Shared.Maid.spec`) can be
+ * resolved to repo-relative filesystem paths.
+ */
+export class SourcemapResolver {
+  private readonly _index: Map<string, string>;
+
+  private constructor(index: Map<string, string>) {
+    this._index = index;
+  }
+
+  /**
+   * Build a resolver from a parsed sourcemap root node.
+   *
+   * @param root - The top-level sourcemap node (typically named after the project)
+   * @param repoRoot - Absolute path to the repo root, used to convert absolute
+   *   `filePaths` entries to repo-relative paths
+   * @param rootAlias - The Roblox service name that the root node maps to in
+   *   test output. Defaults to `"ServerScriptService"`.
+   */
+  static fromSourcemap(
+    root: SourcemapNode,
+    repoRoot: string,
+    rootAlias = 'ServerScriptService'
+  ): SourcemapResolver {
+    const index = new Map<string, string>();
+    _walkNode(root, rootAlias, repoRoot, index);
+    return new SourcemapResolver(index);
+  }
+
+  /**
+   * Resolve a Roblox instance path to a repo-relative filesystem path.
+   *
+   * Strips any trailing `:LINE` suffix before lookup.
+   *
+   * @returns The repo-relative path, or `undefined` if the instance path is
+   *   not in the sourcemap.
+   */
+  resolve(instancePath: string): string | undefined {
+    const cleaned = instancePath.replace(/:\d+$/, '');
+    return this._index.get(cleaned);
+  }
+}
+
+/** Recursively walk the sourcemap tree, populating the index map. */
+function _walkNode(
+  node: SourcemapNode,
+  dottedPath: string,
+  repoRoot: string,
+  index: Map<string, string>
+): void {
+  const luaFile = _findLuaFilePath(node.filePaths);
+  if (luaFile) {
+    const relative = path.relative(repoRoot, luaFile);
+    index.set(dottedPath, relative);
+  }
+
+  if (!node.children) return;
+
+  for (const child of node.children) {
+    _walkNode(child, `${dottedPath}.${child.name}`, repoRoot, index);
+  }
+}
+
+/** Return the first `.lua` or `.luau` file path from a node's filePaths. */
+function _findLuaFilePath(filePaths?: string[]): string | undefined {
+  if (!filePaths) return undefined;
+  return filePaths.find(
+    (fp) => fp.endsWith('.lua') || fp.endsWith('.luau')
+  );
+}

package/src/utils/sourcemap/sourcemap-types.ts

@@ -0,0 +1,12 @@
+/**
+ * A node in the Rojo sourcemap tree (generated by `rojo sourcemap --absolute`).
+ *
+ * Each node represents a Roblox instance and optionally maps to one or more
+ * filesystem paths.
+ */
+export interface SourcemapNode {
+  name: string;
+  className?: string;
+  children?: SourcemapNode[];
+  filePaths?: string[];
+}

package/src/utils/testing/parsers/index.ts

@@ -0,0 +1,2 @@
+export { resolveRobloxTestPath } from './roblox-path-resolver.js';
+export { parseJestLuaOutput } from './jest-lua-parser.js';