feat(models): add URL source type for issues

Author: hanna-skryl

packages/models/docs/models-reference.md

@@ -291,6 +291,20 @@ _Object containing the following properties:_
 
 _(\*) Required._
 
+## FileIssue
+
+Issue with a file source location
+
+_Object containing the following properties:_
+
+| Property            | Description               | Type                                      |
+| :------------------ | :------------------------ | :---------------------------------------- |
+| **`message`** (\*)  | Descriptive error message | `string` (_max length: 1024_)             |
+| **`severity`** (\*) | Severity level            | [IssueSeverity](#issueseverity)           |
+| **`source`** (\*)   | Source file location      | [SourceFileLocation](#sourcefilelocation) |
+
+_(\*) Required._
+
 ## FileName
 
 _String which matches the regular expression `/^(?!.*[ \\/:*?"<>|]).+$/` and has a minimum length of 1._
@@ -374,11 +388,11 @@ Issue information
 
 _Object containing the following properties:_
 
-| Property            | Description               | Type                                      |
-| :------------------ | :------------------------ | :---------------------------------------- |
-| **`message`** (\*)  | Descriptive error message | `string` (_max length: 1024_)             |
-| **`severity`** (\*) | Severity level            | [IssueSeverity](#issueseverity)           |
-| `source`            | Source file location      | [SourceFileLocation](#sourcefilelocation) |
+| Property            | Description                                    | Type                            |
+| :------------------ | :--------------------------------------------- | :------------------------------ |
+| **`message`** (\*)  | Descriptive error message                      | `string` (_max length: 1024_)   |
+| **`severity`** (\*) | Severity level                                 | [IssueSeverity](#issueseverity) |
+| `source`            | Source location of an issue (file path or URL) | [IssueSource](#issuesource)     |
 
 _(\*) Required._
 
@@ -392,6 +406,15 @@ _Enum, one of the following possible values:_
 - `'warning'`
 - `'error'`
 
+## IssueSource
+
+Source location of an issue (file path or URL)
+
+_Union of the following possible types:_
+
+- [SourceFileLocation](#sourcefilelocation)
+- [SourceUrlLocation](#sourceurllocation)
+
 ## MaterialIcon
 
 Icon from VSCode Material Icons extension
@@ -1500,6 +1523,20 @@ _Object containing the following properties:_
 
 _(\*) Required._
 
+## SourceUrlLocation
+
+Location of a DOM element in a web page
+
+_Object containing the following properties:_
+
+| Property       | Description                                   | Type             |
+| :------------- | :-------------------------------------------- | :--------------- |
+| **`url`** (\*) | URL of the web page where the issue was found | `string` (_url_) |
+| `snippet`      | HTML snippet of the element                   | `string`         |
+| `selector`     | CSS selector to locate the element            | `string`         |
+
+_(\*) Required._
+
 ## TableAlignment
 
 Cell alignment
@@ -1579,6 +1616,20 @@ _Object containing the following properties:_
 
 _(\*) Required._
 
+## UrlIssue
+
+Issue with a URL source location
+
+_Object containing the following properties:_
+
+| Property            | Description                             | Type                                    |
+| :------------------ | :-------------------------------------- | :-------------------------------------- |
+| **`message`** (\*)  | Descriptive error message               | `string` (_max length: 1024_)           |
+| **`severity`** (\*) | Severity level                          | [IssueSeverity](#issueseverity)         |
+| **`source`** (\*)   | Location of a DOM element in a web page | [SourceUrlLocation](#sourceurllocation) |
+
+_(\*) Required._
+
 ## Weight
 
 Coefficient for the given score (use weight 0 if only for display)

packages/models/src/index.ts

@@ -4,7 +4,11 @@ export {
 } from './lib/implementation/schemas.js';
 export {
   sourceFileLocationSchema,
+  sourceUrlLocationSchema,
+  issueSourceSchema,
+  type IssueSource,
   type SourceFileLocation,
+  type SourceUrlLocation,
 } from './lib/source.js';
 
 export {
@@ -80,10 +84,14 @@ export {
   validateAsync,
 } from './lib/implementation/validate.js';
 export {
+  fileIssueSchema,
   issueSchema,
   issueSeveritySchema,
+  urlIssueSchema,
+  type FileIssue,
   type Issue,
   type IssueSeverity,
+  type UrlIssue,
 } from './lib/issue.js';
 export {
   formatSchema,

packages/models/src/lib/issue.ts

@@ -1,6 +1,10 @@
 import { z } from 'zod';
 import { MAX_ISSUE_MESSAGE_LENGTH } from './implementation/limits.js';
-import { sourceFileLocationSchema } from './source.js';
+import {
+  issueSourceSchema,
+  sourceFileLocationSchema,
+  sourceUrlLocationSchema,
+} from './source.js';
 
 export const issueSeveritySchema = z.enum(['info', 'warning', 'error']).meta({
   title: 'IssueSeverity',
@@ -15,10 +19,26 @@ export const issueSchema = z
       .max(MAX_ISSUE_MESSAGE_LENGTH)
       .meta({ description: 'Descriptive error message' }),
     severity: issueSeveritySchema,
-    source: sourceFileLocationSchema.optional(),
+    source: issueSourceSchema.optional(),
   })
   .meta({
     title: 'Issue',
     description: 'Issue information',
   });
 export type Issue = z.infer<typeof issueSchema>;
+
+export const fileIssueSchema = issueSchema
+  .extend({ source: sourceFileLocationSchema })
+  .meta({
+    title: 'FileIssue',
+    description: 'Issue with a file source location',
+  });
+export type FileIssue = z.infer<typeof fileIssueSchema>;
+
+export const urlIssueSchema = issueSchema
+  .extend({ source: sourceUrlLocationSchema })
+  .meta({
+    title: 'UrlIssue',
+    description: 'Issue with a URL source location',
+  });
+export type UrlIssue = z.infer<typeof urlIssueSchema>;

packages/models/src/lib/issue.unit.test.ts

@@ -23,6 +23,32 @@ describe('issueSchema', () => {
     ).not.toThrow();
   });
 
+  it('should accept a valid issue with source URL information', () => {
+    expect(() =>
+      issueSchema.parse({
+        message: 'Image is missing alt attribute',
+        severity: 'error',
+        source: {
+          url: 'https://example.com/page',
+          snippet: '<img src="logo.png">',
+          selector: 'img.logo',
+        },
+      }),
+    ).not.toThrow();
+  });
+
+  it('should accept issue with URL source without optional fields', () => {
+    expect(() =>
+      issueSchema.parse({
+        message: 'Accessibility issue found',
+        severity: 'warning',
+        source: {
+          url: 'https://example.com',
+        },
+      }),
+    ).not.toThrow();
+  });
+
   it('should throw for a missing message', () => {
     expect(() =>
       issueSchema.parse({

packages/models/src/lib/source.ts

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import {
   filePathSchema,
   filePositionSchema,
+  urlSchema,
 } from './implementation/schemas.js';
 
 export const sourceFileLocationSchema = z
@@ -17,3 +18,31 @@ export const sourceFileLocationSchema = z
   });
 
 export type SourceFileLocation = z.infer<typeof sourceFileLocationSchema>;
+
+export const sourceUrlLocationSchema = z
+  .object({
+    url: urlSchema.meta({
+      description: 'URL of the web page where the issue was found',
+    }),
+    snippet: z.string().optional().meta({
+      description: 'HTML snippet of the element',
+    }),
+    selector: z.string().optional().meta({
+      description: 'CSS selector to locate the element',
+    }),
+  })
+  .meta({
+    title: 'SourceUrlLocation',
+    description: 'Location of a DOM element in a web page',
+  });
+
+export type SourceUrlLocation = z.infer<typeof sourceUrlLocationSchema>;
+
+export const issueSourceSchema = z
+  .union([sourceFileLocationSchema, sourceUrlLocationSchema])
+  .meta({
+    title: 'IssueSource',
+    description: 'Source location of an issue (file path or URL)',
+  });
+
+export type IssueSource = z.infer<typeof issueSourceSchema>;

packages/models/src/lib/source.unit.test.ts

@@ -0,0 +1,102 @@
+import {
+  issueSourceSchema,
+  sourceFileLocationSchema,
+  sourceUrlLocationSchema,
+} from './source.js';
+
+describe('sourceFileLocationSchema', () => {
+  it('should accept valid file location with position', () => {
+    expect(() =>
+      sourceFileLocationSchema.parse({
+        file: 'src/index.ts',
+        position: { startLine: 10, endLine: 15 },
+      }),
+    ).not.toThrow();
+  });
+
+  it('should accept file location without position', () => {
+    expect(() =>
+      sourceFileLocationSchema.parse({ file: 'src/utils.ts' }),
+    ).not.toThrow();
+  });
+
+  it('should reject empty file path', () => {
+    expect(() => sourceFileLocationSchema.parse({ file: '' })).toThrow(
+      'Too small',
+    );
+  });
+});
+
+describe('sourceUrlLocationSchema', () => {
+  it('should accept valid URL location with all fields', () => {
+    expect(() =>
+      sourceUrlLocationSchema.parse({
+        url: 'https://example.com/page',
+        snippet: '<img src="logo.png">',
+        selector: 'img.logo',
+      }),
+    ).not.toThrow();
+  });
+
+  it('should accept URL location with only required url field', () => {
+    expect(() =>
+      sourceUrlLocationSchema.parse({ url: 'https://example.com' }),
+    ).not.toThrow();
+  });
+
+  it('should accept URL location with snippet only', () => {
+    expect(() =>
+      sourceUrlLocationSchema.parse({
+        url: 'https://example.com/dashboard',
+        snippet: '<button disabled>Submit</button>',
+      }),
+    ).not.toThrow();
+  });
+
+  it('should accept URL location with selector only', () => {
+    expect(() =>
+      sourceUrlLocationSchema.parse({
+        url: 'https://example.com/form',
+        selector: '#submit-btn',
+      }),
+    ).not.toThrow();
+  });
+
+  it('should reject invalid URL', () => {
+    expect(() =>
+      sourceUrlLocationSchema.parse({ url: 'not-a-valid-url' }),
+    ).toThrow('Invalid URL');
+  });
+
+  it('should reject missing URL', () => {
+    expect(() =>
+      sourceUrlLocationSchema.parse({ snippet: '<div>No URL provided</div>' }),
+    ).toThrow('Invalid input');
+  });
+});
+
+describe('issueSourceSchema', () => {
+  it('should accept file-based source', () => {
+    expect(() =>
+      issueSourceSchema.parse({
+        file: 'src/app.ts',
+        position: { startLine: 1 },
+      }),
+    ).not.toThrow();
+  });
+
+  it('should accept URL-based source', () => {
+    expect(() =>
+      issueSourceSchema.parse({
+        url: 'https://example.com',
+        selector: '#main',
+      }),
+    ).not.toThrow();
+  });
+
+  it('should reject source with neither file nor url', () => {
+    expect(() =>
+      issueSourceSchema.parse({ position: { startLine: 1 } }),
+    ).toThrow('Invalid input');
+  });
+});