@askviraj/linter 1.1.0 → 1.1.3

package/node_modules/@rviscomi/capo.js/package.json

@@ -1,6 +1,9 @@
 {
   "name": "@rviscomi/capo.js",
-  "version": "2.1.0",
+  "version": "2.2.0",
+  "publishConfig": {
+    "access": "public"
+  },
   "description": "Get your ﹤𝚑𝚎𝚊𝚍﹥ in order",
   "author": "Rick Viscomi",
   "license": "Apache-2.0",
@@ -14,13 +17,12 @@
   "homepage": "https://rviscomi.github.io/capo.js/",
   "files": [
     "src",
-    "dist",
-    "crx",
-    "docs"
+    "dist"
   ],
   "type": "module",
   "main": "dist/index.cjs",
   "module": "src/index.js",
+  "types": "./dist/types/index.d.ts",
   "alias": {
     "@rviscomi/capo.js": "./src/index.js",
     "@rviscomi/capo.js/adapters/browser": "./src/adapters/browser.js",
@@ -29,34 +31,42 @@
   },
   "exports": {
     ".": {
+      "types": "./dist/types/index.d.ts",
       "import": "./src/index.js",
       "require": "./dist/index.cjs"
     },
     "./adapters": {
+      "types": "./dist/types/adapters/index.d.ts",
       "import": "./src/adapters/index.js",
       "require": "./dist/adapters/index.cjs"
     },
     "./adapters/browser": {
+      "types": "./dist/types/adapters/browser.d.ts",
       "import": "./src/adapters/browser.js",
       "require": "./dist/adapters/browser.cjs"
     },
     "./rules": {
+      "types": "./dist/types/lib/rules.d.ts",
       "import": "./src/lib/rules.js",
       "require": "./dist/lib/rules.cjs"
     },
     "./validation": {
+      "types": "./dist/types/lib/validation.d.ts",
       "import": "./src/lib/validation.js",
       "require": "./dist/lib/validation.cjs"
     },
     "./lib/io": {
+      "types": "./dist/types/lib/io.d.ts",
       "import": "./src/lib/io.js",
       "require": "./dist/lib/io.cjs"
     },
     "./lib/options": {
+      "types": "./dist/types/lib/options.d.ts",
       "import": "./src/lib/options.js",
       "require": "./dist/lib/options.cjs"
     },
     "./adapters/test-suite": {
+      "types": "./dist/types/adapters/test-suite.d.ts",
       "import": "./src/adapters/test-suite.js",
       "require": "./dist/adapters/test-suite.cjs"
     }
@@ -65,15 +75,14 @@
     "doc": "docs"
   },
   "targets": {
-
-    "crx": {
-      "source": "src/crx/capo.js",
-      "distDir": "crx",
+    "chrome": {
+      "source": "src/extension/capo.js",
+      "distDir": "dist/chrome",
       "sourceMap": false
     },
-    "crx-options": {
-      "source": "src/crx/options.js",
-      "distDir": "crx/options",
+    "chrome-options": {
+      "source": "src/extension/options.js",
+      "distDir": "dist/chrome/options",
       "sourceMap": false
     },
     "web": {
@@ -85,8 +94,13 @@
     }
   },
   "scripts": {
+    "typecheck": "tsc --noEmit",
+    "typecheck:ext": "tsc --noEmit -p tsconfig.extension.json",
+    "typecheck:test": "tsc --noEmit -p tsconfig.test.json",
+    "build:types": "tsc -p tsconfig.json",
     "watch": "parcel watch",
-    "build": "npm run build:cjs && parcel build",
+    "build": "npm run build:cjs && npm run build:types && parcel build && node scripts/build-extension.js",
+    "package:source": "zip -r -q dist/source.zip . -x \"node_modules/*\" \"dist/*\" \".git/*\" \".parcel-cache/*\" \"docs/node_modules/*\" \"docs/.astro/*\" \"docs/dist/*\" \".github/*\" \"*/.DS_Store\" \".DS_Store\"",
     "build:cjs": "esbuild src/index.js src/analyzer.js src/adapters/adapter.js src/adapters/index.js src/adapters/browser.js src/lib/rules.js src/lib/validation.js src/lib/io.js src/lib/options.js src/lib/colors.js src/adapters/test-suite.js --bundle --platform=node --format=cjs --outdir=dist --out-extension:.js=.cjs",
     "test": "node --test tests/**/*.test.js",
     "test:watch": "node --test --watch tests/**/*.test.js",
@@ -97,9 +111,13 @@
   },
   "devDependencies": {
     "@parcel/cache": "^2.16.4",
-    "dedent": "^1.7.0",
-    "esbuild": "^0.27.3",
-    "jsdom": "^27.0.1",
-    "parcel": "latest"
+    "@types/jsdom": "^28.0.3",
+    "@types/node": "^26.1.1",
+    "chrome-types": "^0.1.436",
+    "dedent": "^1.7.2",
+    "esbuild": "^0.28.1",
+    "jsdom": "^29.1.1",
+    "parcel": "^2.16.4",
+    "typescript": "^7.0.2"
   }
 }

package/node_modules/@rviscomi/capo.js/src/adapters/adapter.js

@@ -4,10 +4,18 @@
  * This file defines the contract that all adapters must implement.
  * Adapters abstract away environment-specific operations (browser DOM vs AST nodes)
  * to make capo.js core logic reusable across different contexts.
- * 
- * @interface HTMLAdapter
  */
 
+/**
+ * Source location information for a node
+ * @typedef {Object} SourceLocation
+ * @property {number} line
+ * @property {number} column
+ * @property {number} [endLine]
+ * @property {number} [endColumn]
+ */
+
+/** @type {readonly string[]} */
 const REQUIRED_METHODS = [
   'isElement',
   'getTagName',
@@ -22,7 +30,7 @@ const REQUIRED_METHODS = [
 ];
 
 /**
- * Base adapter interface (documentation only)
+ * Base adapter interface
  * 
  * Actual adapters should implement all these methods.
  * This serves as both documentation and a reference implementation.
@@ -124,7 +132,7 @@ export class AdapterInterface {
   /**
    * Get source location for a node (optional, for linting)
    * @param {any} node - Element node
-   * @returns {{ line: number, column: number, endLine?: number, endColumn?: number } | null}
+   * @returns {SourceLocation | null}
    */
   getLocation(node) {
     return null;
@@ -146,8 +154,11 @@ export class AdapterInterface {
  * @throws {Error} If adapter is missing required methods
  */
 export function validateAdapter(adapter) {
+  if (!adapter || typeof adapter !== 'object') {
+    throw new Error('Adapter must be an object');
+  }
   for (const method of REQUIRED_METHODS) {
-    if (typeof adapter[method] !== 'function') {
+    if (typeof /** @type {Record<string, any>} */ (adapter)[method] !== 'function') {
       throw new Error(`Adapter missing required method: ${method}()`);
     }
   }

package/node_modules/@rviscomi/capo.js/src/adapters/browser.js

@@ -14,10 +14,9 @@ import { AdapterInterface } from './adapter.js';
  * Wraps native DOM Element APIs for use with capo.js core logic.
  * 
  * @extends AdapterInterface
- * @implements {HTMLAdapter}
  * @example
  * import { BrowserAdapter } from './adapters/browser.js';
- * import { Analyzer } from '../analyzer.js';
+ * import { analyzeHead } from '../analyzer.js';
  * 
  * const adapter = new BrowserAdapter();
  * const head = document.querySelector('head');
@@ -26,6 +25,7 @@ import { AdapterInterface } from './adapter.js';
 export class BrowserAdapter extends AdapterInterface {
   /**
    * Check if node is an Element (not text, comment, etc.)
+   * @override
    * @param {any} node - The node to check
    * @returns {boolean}
    */
@@ -37,6 +37,7 @@ export class BrowserAdapter extends AdapterInterface {
 
   /**
    * Get the tag name of an element (lowercase)
+   * @override
    * @param {any} node - Element node
    * @returns {string} - Tag name like 'meta', 'link', 'script'
    */
@@ -44,11 +45,14 @@ export class BrowserAdapter extends AdapterInterface {
     if (!node || !node.tagName) {
       return '';
     }
-    return node.tagName.toLowerCase();
+    const name = node.tagName.toLowerCase();
+    if (name === 'static-head') return 'head';
+    return name;
   }
 
   /**
    * Get attribute value from element
+   * @override
    * @param {any} node - Element node
    * @param {string} attrName - Attribute name (case-insensitive)
    * @returns {string | null} - Attribute value or null if not found
@@ -62,6 +66,7 @@ export class BrowserAdapter extends AdapterInterface {
 
   /**
    * Check if element has a specific attribute
+   * @override
    * @param {any} node - Element node
    * @param {string} attrName - Attribute name (case-insensitive)
    * @returns {boolean} - True if attribute exists
@@ -75,6 +80,7 @@ export class BrowserAdapter extends AdapterInterface {
 
   /**
    * Get all attribute names for an element
+   * @override
    * @param {any} node - Element node
    * @returns {string[]} - Array of attribute names
    */
@@ -87,6 +93,7 @@ export class BrowserAdapter extends AdapterInterface {
 
   /**
    * Get text content of a node (for inline scripts/styles)
+   * @override
    * @param {any} node - Element node
    * @returns {string} - Text content
    */
@@ -99,11 +106,26 @@ export class BrowserAdapter extends AdapterInterface {
 
   /**
    * Get child elements of a node
+   * @override
    * @param {any} node - Parent node
    * @returns {any[]} - Array of child element nodes (excluding text/comment nodes)
    */
   getChildren(node) {
-    if (!node || !node.children) {
+    if (!node) {
+      return [];
+    }
+    if (this.getTagName(node) === 'noscript') {
+      const content = node.innerHTML || '';
+      if (content.trim()) {
+        const doc = node.ownerDocument || (typeof document !== 'undefined' ? document : null);
+        if (doc) {
+          const temp = doc.createElement('div');
+          temp.innerHTML = content;
+          return Array.from(temp.children);
+        }
+      }
+    }
+    if (!node.children) {
       return [];
     }
     return Array.from(node.children);
@@ -111,6 +133,7 @@ export class BrowserAdapter extends AdapterInterface {
 
   /**
    * Get parent element of a node
+   * @override
    * @param {any} node - Child node
    * @returns {any | null} - Parent element node, or null if no parent
    */
@@ -123,6 +146,7 @@ export class BrowserAdapter extends AdapterInterface {
 
   /**
    * Get sibling elements of a node
+   * @override
    * @param {any} node - Element node
    * @returns {any[]} - Array of sibling element nodes (excluding the node itself)
    */
@@ -143,6 +167,7 @@ export class BrowserAdapter extends AdapterInterface {
    * Browser DOM elements don't have source location information,
    * so this always returns null.
    * 
+   * @override
    * @param {any} node - Element node
    * @returns {null}
    */
@@ -153,6 +178,7 @@ export class BrowserAdapter extends AdapterInterface {
 
   /**
    * Stringify element for logging/debugging
+   * @override
    * @param {any} node - Element node
    * @returns {string} - String representation like "<meta charset='utf-8'>"
    */

package/node_modules/@rviscomi/capo.js/src/adapters/test-suite.js

@@ -24,13 +24,17 @@ import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
 import { validateAdapter } from './adapter.js';
 
+/**
+ * @typedef {Object} AdapterTestSuiteOptions
+ * @property {(html: string) => any} createElement - Function that creates test nodes from HTML strings
+ * @property {boolean} [supportsLocation=false] - Whether adapter supports getLocation()
+ */
+
 /**
  * Run the standard adapter test suite
  * 
- * @param {Function} AdapterClass - The adapter class to test
- * @param {Object} options - Test configuration
- * @param {Function} options.createElement - Function that creates test nodes from HTML strings
- * @param {boolean} [options.supportsLocation=false] - Whether adapter supports getLocation()
+ * @param {new () => any} AdapterClass - The adapter class to test
+ * @param {AdapterTestSuiteOptions} options - Test configuration
  */
 export function runAdapterTestSuite(AdapterClass, options) {
   const { createElement, supportsLocation = false } = options;
@@ -39,6 +43,7 @@ export function runAdapterTestSuite(AdapterClass, options) {
     throw new Error('createElement function is required in test options');
   }
 
+  /** @type {any} */
   let adapter;
 
   function setup() {
@@ -240,7 +245,6 @@ export function runAdapterTestSuite(AdapterClass, options) {
         assert.ok(parent, 'Should return a parent');
         assert.equal(adapter.getTagName(parent), 'head');
       } else {
-        // If createElement doesn't support nested structures, skip this test
         assert.ok(true, 'Skipped - createElement does not support nested structures');
       }
     });
@@ -249,7 +253,6 @@ export function runAdapterTestSuite(AdapterClass, options) {
       setup();
       const el = createElement('<meta charset="utf-8">');
       const parent = adapter.getParent(el);
-      // Parent may be null or the synthetic container
       assert.ok(parent === null || adapter.isElement(parent), 'Should return null or element');
     });
 
@@ -272,7 +275,6 @@ export function runAdapterTestSuite(AdapterClass, options) {
         assert.ok(siblings.length > 0, 'Should have siblings');
         assert.ok(!siblings.includes(meta), 'Should not include element itself');
       } else {
-        // If createElement doesn't support nested structures, skip this test
         assert.ok(true, 'Skipped - createElement does not support nested structures');
       }
     });
@@ -285,7 +287,7 @@ export function runAdapterTestSuite(AdapterClass, options) {
         const meta = children[0];
         const siblings = adapter.getSiblings(meta);
         assert.ok(!siblings.includes(meta), 'Should not include element itself');
-        assert.ok(!siblings.some(s => s === meta), 'Should not contain element itself');
+        assert.ok(!siblings.some((/** @type {any} */ s) => s === meta), 'Should not contain element itself');
       } else {
         assert.ok(true, 'Skipped - createElement does not support nested structures');
       }
@@ -296,7 +298,6 @@ export function runAdapterTestSuite(AdapterClass, options) {
       const el = createElement('<meta charset="utf-8">');
       const siblings = adapter.getSiblings(el);
       assert.ok(Array.isArray(siblings), 'Should return an array');
-      // May be empty if no siblings, or may contain siblings if createElement adds container
     });
 
     it('should handle null node gracefully', () => {
@@ -373,7 +374,7 @@ export function runAdapterTestSuite(AdapterClass, options) {
  * This is a lighter-weight alternative that just checks the adapter
  * implements all required methods without full behavior testing.
  * 
- * @param {Function} AdapterClass - The adapter class to test
+ * @param {new () => any} AdapterClass - The adapter class to test
  */
 export function testAdapterCompliance(AdapterClass) {
   describe('Adapter Compliance', () => {

package/node_modules/@rviscomi/capo.js/src/analyzer.js

@@ -9,49 +9,69 @@ import * as rules from './lib/rules.js';
 import { getValidationWarnings, getCustomValidations } from './lib/validation.js';
 
 /**
- * @typedef {Object} AnalysisResult
- * @property {Array<WeightInfo>} weights - Weight information for each element
- * @property {Array<ValidationWarning>} validationWarnings - Document-level validation warnings
- * @property {Array<CustomValidation>} customValidations - Element-level validation warnings
- * @property {any} headElement - Reference to the analyzed head element
- */
-
-/**
+ * @typedef {import('./adapters/adapter.js').AdapterInterface} AdapterInterface
+ * 
  * @typedef {Object} WeightInfo
  * @property {any} element - The DOM/AST element
  * @property {number} weight - Computed weight (0-10)
- * @property {string} category - Weight category name (META, TITLE, etc.)
  */
 
 /**
  * @typedef {Object} ValidationWarning
+ * @property {string} [ruleId] - The rule identifier
  * @property {string} warning - Warning message
- * @property {any|Array<any>} [element] - Associated element(s)
+ * @property {any} [element] - Associated element
  * @property {Array<any>} [elements] - Associated elements array
  */
 
 /**
  * @typedef {Object} CustomValidation
+ * @property {string} [ruleId] - The rule identifier
  * @property {any} element - The element with validation issues
  * @property {Array<string>} warnings - Validation warning messages
+ * @property {any} [payload] - Extra diagnostic payload
+ */
+
+/**
+ * @typedef {Object} AnalysisResult
+ * @property {Array<WeightInfo>} weights - Weight information for each element
+ * @property {Array<ValidationWarning>} validationWarnings - Document-level validation warnings
+ * @property {Array<CustomValidation>} customValidations - Element-level validation warnings
+ * @property {any} headElement - Reference to the analyzed head element
+ */
+
+/**
+ * @typedef {Object} OrderingViolation
+ * @property {number} index
+ * @property {any} currentElement
+ * @property {any} nextElement
+ * @property {number} currentWeight
+ * @property {number} nextWeight
+ * @property {string} currentCategory
+ * @property {string} nextCategory
+ * @property {string} message
+ */
+
+/**
+ * @typedef {AnalysisResult & { orderingViolations: Array<OrderingViolation> }} AnalysisResultWithOrdering
+ */
+
+/**
+ * @typedef {Object} AnalyzeHeadOptions
+ * @property {boolean} [includeValidation=true] - Whether to include document-level validation warnings
+ * @property {boolean} [includeCustomValidations=true] - Whether to include element-level custom validations
  */
 
 /**
  * Analyze the head element and return element weights, validation warnings, and custom validations.
  *
  * @param {any} headNode - The head element to analyze
- * @param {Object} adapter - Adapter for element operations
- * @param {Object} [options={}] - Analysis options
- * @param {boolean} [options.includeValidation=true] - Whether to include document-level validation warnings
- * @param {boolean} [options.includeCustomValidations=true] - Whether to include element-level custom validations
- * @returns {Object} Analysis results
- * @returns {Array} returns.weights - Array of element weight objects
- * @returns {Array} returns.validationWarnings - Document-level validation warnings
- * @returns {Array} returns.customValidations - Element-level custom validation results
- * @returns {any} returns.headElement - The analyzed head element
+ * @param {AdapterInterface} adapter - Adapter for element operations
+ * @param {AnalyzeHeadOptions} [options={}] - Analysis options
+ * @returns {AnalysisResult} Analysis results
  *
  * @example
- * const adapter = new HtmlEslintAdapter();
+ * const adapter = new BrowserAdapter();
  * const results = analyzeHead(head, adapter);
  * 
  * console.log(`Found ${results.weights.length} elements`);
@@ -88,11 +108,12 @@ export function analyzeHead(headNode, adapter, options = {}) {
  * Get custom validations for all elements in head
  * 
  * @param {any} headNode - The <head> element
- * @param {Object} adapter - HTMLAdapter implementation
+ * @param {AdapterInterface} adapter - HTMLAdapter implementation
  * @returns {Array<CustomValidation>}
  * @private
  */
 function getElementValidations(headNode, adapter) {
+  /** @type {Array<CustomValidation>} */
   const customValidations = [];
   const children = adapter.getChildren(headNode);
 
@@ -137,7 +158,7 @@ export function getWeightCategory(weight) {
  * Check if elements are in optimal order
  * 
  * @param {Array<WeightInfo>} weights - Weight information array
- * @returns {Array<Object>} Array of ordering violations
+ * @returns {Array<OrderingViolation>} Array of ordering violations
  * 
  * @example
  * const weights = analyzeHead(head, adapter).weights;
@@ -145,6 +166,7 @@ export function getWeightCategory(weight) {
  * console.log(`${violations.length} ordering issues found`);
  */
 export function checkOrdering(weights) {
+  /** @type {Array<OrderingViolation>} */
   const violations = [];
 
   for (let i = 0; i < weights.length - 1; i++) {
@@ -176,9 +198,9 @@ export function checkOrdering(weights) {
  * Convenience function that combines analyzeHead() and checkOrdering()
  * 
  * @param {any} headNode - The <head> element
- * @param {Object} adapter - HTMLAdapter implementation
- * @param {Object} [options={}] - Analysis options
- * @returns {Object} Combined analysis with weights, violations, and validations
+ * @param {AdapterInterface} adapter - HTMLAdapter implementation
+ * @param {AnalyzeHeadOptions} [options={}] - Analysis options
+ * @returns {AnalysisResultWithOrdering} Combined analysis with weights, violations, and validations
  * 
  * @example
  * const analysis = analyzeHeadWithOrdering(head, adapter);

package/node_modules/@rviscomi/capo.js/src/extension/README.md

@@ -0,0 +1,53 @@
+# Capo Browser Extension Source Code
+
+This directory contains the source code for the Capo browser extension (available for Chrome and Firefox).
+
+## Build Instructions
+
+This extension is built from source using Node.js and Parcel. Follow these steps to produce the exact binary package submitted for verification.
+
+### Requirements
+
+- **Operating System:** macOS, Linux, or Windows.
+- **Environment:** 
+  - **Node.js:** v18.0.0 or higher (v22.x recommended).
+  - **npm:** v9.0.0 or higher (v10.x recommended).
+
+### 1. Installation of Prerequisites
+
+If Node.js and npm are not installed:
+- **macOS (via Homebrew):** `brew install node`
+- **Windows / Linux:** Download the installer from [nodejs.org](https://nodejs.org/).
+
+Verify installation:
+```bash
+node -v
+npm -v
+```
+
+### 2. Install Project Dependencies
+
+Run the following command from the root of the source code directory to install all required development and build dependencies:
+
+```bash
+npm install
+```
+
+### 3. Execute the Build Script
+
+Run the build script to compile and package the extension:
+
+```bash
+npm run build
+```
+
+This runs:
+- `npm run build:cjs`: Compiles CommonJS bundles using `esbuild`.
+- `parcel build`: Compiles, bundles, and minifies the extension source code (`src/extension/capo.js` and `src/extension/options.js`) using `Parcel`.
+- `node scripts/build-extension.js`: Copies static files, generates the Firefox-compatible manifest, and packages them.
+
+### 4. Locate Build Outputs
+
+Once the build is complete:
+- The compiled Firefox extension files will be in `dist/firefox/`.
+- The final zip package submitted to Mozilla is located at `dist/firefox.zip`.

package/node_modules/@rviscomi/capo.js/src/extension/background.js

@@ -0,0 +1,7 @@
+chrome.runtime.onInstalled.addListener(function (details) {
+  if (details.reason == "install") {
+    chrome.tabs.create({
+      url: "https://rviscomi.github.io/capo.js/user/extension/?utm_source=installed&utm_medium=extension&utm_campaign=capo",
+    });
+  }
+});

package/node_modules/@rviscomi/capo.js/src/extension/capo.css

@@ -0,0 +1,59 @@
+body {
+  padding: 0;
+  margin: 0;
+  height: 60px;
+  background-color: #ccc;
+}
+
+.capo-container {
+  display: flex;
+  align-content: stretch;
+  width: 600px;
+}
+
+.capo-head-element {
+  content: '';
+  width: 100%;
+  height: 30px;
+  box-sizing: border-box;
+}
+.capo-head-element.invalid {
+  background-image: repeating-linear-gradient(
+    45deg,
+    rgba(0, 0, 0, 0),
+    rgba(0, 0, 0, 0) 3px,
+    rgba(255, 0, 0, 0.3) 3px,
+    rgba(255, 0, 0, 0.3) 6px
+  );
+}
+.capo-head-element.invalid:is(
+  [data-weight="10"],
+  [data-weight="9"],
+  [data-weight="8"],
+  [data-weight="7"]
+) {
+  background-image: repeating-linear-gradient(
+    45deg,
+    rgba(255, 255, 255, 0.3),
+    rgba(255, 255, 255, 0.3) 3px,
+    rgba(0, 0, 0, 0) 3px,
+    rgba(0, 0, 0, 0) 6px
+  );
+}.capo-head-element.invalid:is(
+  [data-weight="2"],
+  [data-weight="1"]
+) {
+  background-image: repeating-linear-gradient(
+    45deg,
+    rgba(255, 255, 255, 0.3),
+    rgba(255, 255, 255, 0.3) 3px,
+    rgba(255, 0, 0, 0.3) 3px,
+    rgba(255, 0, 0, 0.3) 6px
+  );
+}
+.capo-head-element:hover {
+  box-shadow: inset 0 0 0 9999px rgba(0, 0, 0, 0.1);
+}
+.capo-head-element.invalid:hover {
+  box-shadow: inset 0 0 0 9999px rgba(255, 0, 0, 0.1);
+}

package/node_modules/@rviscomi/capo.js/src/extension/capo.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <link rel="stylesheet" href="capo.css">
+  </head>
+  <body>
+    <div id="actual" class="capo-container"></div>
+    <div id="sorted" class="capo-container"></div>
+
+    <script type="module" src="chrome.js"></script>
+  </body>
+</html>