obsohtml 1.9.9 → 1.10.0

package/.github/dependabot.yml

@@ -6,6 +6,8 @@ updates:
     directory: "/"
     schedule:
       interval: "monthly"
+    cooldown:
+      default-days: 7
   - package-ecosystem: "github-actions"
     directory: "/"
     schedule:

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+As of version 1.10.0, all notable changes to ObsoHTML are documented in this file, which is (mostly) AI-generated and (always) human-edited. Dependency updates may or may not be called out specifically.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.10.0] - 2026-04-11
+
+### Added
+
+- Added programmatic API: `checkMarkup(html)` returns `{ elements, attributes }` arrays for use in other tools; `obsoleteElements` and `obsoleteAttributes` are now exported directly
+- Added TypeScript declaration file (`src/index.d.ts`)

package/README.md

@@ -2,13 +2,13 @@
 
 [![npm version](https://img.shields.io/npm/v/obsohtml.svg)](https://www.npmjs.com/package/obsohtml) [![Build status](https://github.com/j9t/obsohtml/workflows/Tests/badge.svg)](https://github.com/j9t/obsohtml/actions) [![Socket](https://badge.socket.dev/npm/package/obsohtml)](https://socket.dev/npm/package/obsohtml)
 
-ObsoHTML is a Node.js script designed to scan HTML, PHP, Nunjucks, Twig, JavaScript, and TypeScript files for obsolete and proprietary HTML elements and attributes. It helps you identify and update deprecated HTML code to be sure to use web standards.
+ObsoHTML is a Node.js tool designed to scan HTML, PHP, Nunjucks, Twig, JavaScript, and TypeScript files for obsolete and proprietary HTML elements and attributes. It helps you identify and update deprecated HTML code to be sure to use web standards.
 
 ObsoHTML has inherent limitations and may not find all obsolete elements and attributes. If you run into a problem, please [file an issue](https://github.com/j9t/obsohtml/issues).
 
 ## Usage
 
-### 1. As a Node Module
+### 1. Via CLI
 
 #### Installation
 
@@ -18,11 +18,13 @@ npm i obsohtml
 
 (To install ObsoHTML globally, use the `-g` flag, as in `npm i -g obsohtml`.)
 
+To use ObsoHTML without installing, run it via `npx obsohtml`. To use it as a standalone script, [download or fork the source repository](https://github.com/j9t/obsohtml) and run `node bin/obsohtml.js` directly—the same options apply.
+
 #### Execution
 
-The script accepts a folder or file path as a command line option, which can be specified in both short form (`-f`) and long form (`--folder`). The path can be either absolute or relative.
+ObsoHTML accepts a folder or file path as a command line option, which can be specified in both short form (`-f`) and long form (`--folder`). The path can be either absolute or relative.
 
-The script can be run in “verbose” mode by appending `-v` or `--verbose` to the command. This will show information about files and directories that were skipped.
+ObsoHTML can be run in “verbose” mode by appending `-v` or `--verbose` to the command. This will show information about files and directories that were skipped.
 
 ##### Example Commands
 
@@ -44,37 +46,32 @@ Specify a folder using a relative path:
 npx obsohtml -f ../path/to/folder
 ```
 
-### 2. As a Standalone Script
-
-#### Installation
-
-Download or fork [the source repository](https://github.com/j9t/obsohtml).
+### 2. Programmatic API
 
-#### Execution
+ObsoHTML can be imported as a module to check HTML strings in your own tooling:
 
-As mentioned above, the script accepts a folder (`-f`, `--folder`) and can be run in “verbose” mode (`-v`, `--verbose`).
+```js
+import { checkMarkup, obsoleteElements, obsoleteAttributes } from 'obsohtml';
 
-##### Example Commands
+const { elements, attributes } = checkMarkup('<center>Hello</center>');
+// elements: ['center']
+// attributes: []
+```
 
-(All commands as run from the root directory of the downloaded repository.)
+#### `checkMarkup(html)`
 
-Use the default directory (user home directory):
+Checks an HTML string for obsolete or proprietary elements and attributes.
 
-```console
-node bin/obsohtml.js
-```
+* **Parameter**: `html` (string)—the HTML content to check
+* **Returns**: `{ elements: string[], attributes: string[] }`—arrays of found obsolete element and attribute names
 
-Specify a folder using an absolute path (easiest and most common use case):
+#### `obsoleteElements`
 
-```console
-node bin/obsohtml.js -f /path/to/folder
-```
+Array of obsolete or proprietary HTML element names checked by ObsoHTML.
 
-Specify a folder using a relative path:
+#### `obsoleteAttributes`
 
-```console
-node bin/obsohtml.js -f ../path/to/folder
-```
+Array of obsolete or proprietary HTML attribute names checked by ObsoHTML.
 
 ## Output
 

package/bin/obsohtml.js

@@ -5,32 +5,10 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { styleText } from 'node:util';
+import { checkMarkup } from '../src/index.js';
 
 const program = new Command();
 
-// List of obsolete or proprietary HTML elements
-const obsoleteElements = [
-  'acronym', 'applet', 'basefont', 'bgsound', 'big', 'blink', 'center', 'command', 'content', 'dir', 'element', 'font', 'frame', 'frameset', 'image', 'isindex', 'keygen', 'listing', 'marquee', 'menuitem', 'multicol', 'nextid', 'nobr', 'noembed', 'noframes', 'param', 'plaintext', 'rb', 'rtc', 'shadow', 'spacer', 'strike', 'tt', 'xmp'
-];
-
-// List of obsolete or proprietary HTML attributes
-const obsoleteAttributes = [
-  'align', 'background', 'bgcolor', 'border', 'frameborder', 'hspace', 'marginheight', 'marginwidth', 'noshade', 'nowrap', 'scrolling', 'valign', 'vspace'
-];
-
-// Pre-compile regexes once at startup
-const elementRegexes = obsoleteElements.map(element => ({
-  element,
-  regex: new RegExp(`<\\s*${element}\\b`, 'i'),
-}));
-
-const attributeRegexes = obsoleteAttributes.map(attribute => ({
-  attribute,
-  // Matches the attribute preceded by whitespace anywhere in a tag, without
-  // requiring it to be the last attribute before the closing bracket.
-  regex: new RegExp(`<[^>]*\\s${attribute}\\b(\\s*=\\s*(?:"[^"]*"|'[^']*'|[^"'\\s>]+))?`, 'i'),
-}));
-
 // Directories to skip during traversal
 const EXCLUDED_DIRS = new Set(['node_modules', '.git', 'dist', 'build', 'vendor']);
 
@@ -42,24 +20,16 @@ let foundObsolete = false;
 
 // Function to find obsolete elements and attributes in a file
 function findObsolete(filePath) {
-  const content = fs.readFileSync(filePath, 'utf8');
-
-  // Check for obsolete elements
-  for (const { element, regex } of elementRegexes) {
-    if (regex.test(content)) {
-      foundObsolete = true;
-      const message = styleText('blue', `Found obsolete element ${styleText('bold', `'${element}'`)} in ${filePath}`);
-      console.log(message);
-    }
+  const { elements, attributes } = checkMarkup(fs.readFileSync(filePath, 'utf8'));
+
+  for (const element of elements) {
+    foundObsolete = true;
+    console.log(styleText('blue', `Found obsolete element ${styleText('bold', `'${element}'`)} in ${filePath}`));
   }
 
-  // Check for obsolete attributes
-  for (const { attribute, regex } of attributeRegexes) {
-    if (regex.test(content)) {
-      foundObsolete = true;
-      const message = styleText('green', `Found obsolete attribute ${styleText('bold', `'${attribute}'`)} in ${filePath}`);
-      console.log(message);
-    }
+  for (const attribute of attributes) {
+    foundObsolete = true;
+    console.log(styleText('green', `Found obsolete attribute ${styleText('bold', `'${attribute}'`)} in ${filePath}`));
   }
 }
 

package/bin/obsohtml.test.js

@@ -5,6 +5,7 @@ import { fileURLToPath } from 'node:url';
 import { describe, test, before, after } from 'node:test';
 import assert from 'node:assert';
 import { stripVTControlCharacters } from 'node:util';
+import { checkMarkup, obsoleteElements, obsoleteAttributes } from '../src/index.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const scriptPath = path.join(__dirname, 'obsohtml.js');
@@ -120,4 +121,78 @@ describe('ObsoHTML', () => {
     const { stderr } = run(['-f', path.join(tempDir, 'nonexistent'), '-v']);
     assert.ok(stderr.includes('Skipping non-existent directory'));
   });
+});
+
+describe('`obsoleteElements`', () => {
+  test('Export as a non-empty array of strings', () => {
+    assert.ok(Array.isArray(obsoleteElements));
+    assert.ok(obsoleteElements.length > 0);
+    assert.ok(obsoleteElements.every(e => typeof e === 'string'));
+  });
+});
+
+describe('`obsoleteAttributes`', () => {
+  test('Export as a non-empty array of strings', () => {
+    assert.ok(Array.isArray(obsoleteAttributes));
+    assert.ok(obsoleteAttributes.length > 0);
+    assert.ok(obsoleteAttributes.every(a => typeof a === 'string'));
+  });
+});
+
+describe('`checkMarkup`', () => {
+  test('Return empty arrays for clean HTML', () => {
+    const result = checkMarkup('<p>Hello <strong>world</strong></p>');
+    assert.deepEqual(result, { elements: [], attributes: [] });
+  });
+
+  test('Return empty arrays for an empty string', () => {
+    const result = checkMarkup('');
+    assert.deepEqual(result, { elements: [], attributes: [] });
+  });
+
+  test('Throw a TypeError for non-string input', () => {
+    assert.throws(() => checkMarkup(null), TypeError);
+    assert.throws(() => checkMarkup(42), TypeError);
+  });
+
+  test('Detect an obsolete element', () => {
+    const { elements, attributes } = checkMarkup('<center>Hello</center>');
+    assert.ok(elements.includes('center'));
+    assert.deepEqual(attributes, []);
+  });
+
+  test('Detect an obsolete attribute', () => {
+    const { elements, attributes } = checkMarkup('<img src="x.jpg" align="left">');
+    assert.deepEqual(elements, []);
+    assert.ok(attributes.includes('align'));
+  });
+
+  test('Detect multiple obsolete elements in one string', () => {
+    const { elements } = checkMarkup('<marquee><blink>Hello</blink></marquee>');
+    assert.ok(elements.includes('marquee'));
+    assert.ok(elements.includes('blink'));
+  });
+
+  test('Detect multiple obsolete attributes in one string', () => {
+    const { attributes } = checkMarkup('<table border="1" bgcolor="#fff"><tr valign="top"></tr></table>');
+    assert.ok(attributes.includes('border'));
+    assert.ok(attributes.includes('bgcolor'));
+    assert.ok(attributes.includes('valign'));
+  });
+
+  test('Detect both obsolete elements and attributes in one string', () => {
+    const { elements, attributes } = checkMarkup('<center><img align="left"></center>');
+    assert.ok(elements.includes('center'));
+    assert.ok(attributes.includes('align'));
+  });
+
+  test('Detect obsolete elements case-insensitively', () => {
+    const { elements } = checkMarkup('<CENTER>Hello</CENTER>');
+    assert.ok(elements.includes('center'));
+  });
+
+  test('Do not detect partial tag name matches', () => {
+    const { elements } = checkMarkup('<centers>Hello</centers>');
+    assert.deepEqual(elements, []);
+  });
 });

package/package.json

@@ -7,6 +7,18 @@
     "commander": "^14.0.0"
   },
   "description": "HTML checker for obsolete and proprietary elements and attributes",
+  "devDependencies": {
+    "@eslint/js": "^10.0.0",
+    "eslint": "^10.1.0",
+    "globals": "^17.0.0",
+    "typescript": "^6.0.2"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    }
+  },
   "funding": "https://github.com/j9t/obsohtml?sponsor=1",
   "homepage": "https://github.com/j9t/obsohtml",
   "keywords": [
@@ -16,22 +28,20 @@
     "semantics"
   ],
   "license": "MIT",
+  "main": "src/index.js",
   "name": "obsohtml",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/j9t/obsohtml.git"
   },
-  "devDependencies": {
-    "@eslint/js": "^10.0.0",
-    "eslint": "^10.0.0",
-    "globals": "^17.0.0"
-  },
   "scripts": {
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "start": "node ./bin/obsohtml.js",
-    "test": "node --test bin/obsohtml.test.js"
+    "test": "npm run test:types && node --test bin/obsohtml.test.js",
+    "test:types": "tsc"
   },
   "type": "module",
-  "version": "1.9.9"
+  "types": "src/index.d.ts",
+  "version": "1.10.0"
 }

package/src/index.d.ts

@@ -0,0 +1,7 @@
+export declare const obsoleteElements: readonly string[];
+export declare const obsoleteAttributes: readonly string[];
+
+export declare function checkMarkup(html: string): {
+  elements: string[];
+  attributes: string[];
+};

package/src/index.js

@@ -0,0 +1,46 @@
+// Obsolete or proprietary HTML elements
+export const obsoleteElements = Object.freeze([
+  'acronym', 'applet', 'basefont', 'bgsound', 'big', 'blink', 'center', 'command', 'content', 'dir', 'element', 'font', 'frame', 'frameset', 'image', 'isindex', 'keygen', 'listing', 'marquee', 'menuitem', 'multicol', 'nextid', 'nobr', 'noembed', 'noframes', 'param', 'plaintext', 'rb', 'rtc', 'shadow', 'spacer', 'strike', 'tt', 'xmp'
+]);
+
+// Obsolete or proprietary HTML attributes
+export const obsoleteAttributes = Object.freeze([
+  'align', 'background', 'bgcolor', 'border', 'frameborder', 'hspace', 'marginheight', 'marginwidth', 'noshade', 'nowrap', 'scrolling', 'valign', 'vspace'
+]);
+
+// Pre-compiled regexes for performance
+const elementRegexes = new Map(
+  obsoleteElements.map(element => [element, new RegExp(`<\\s*${element}\\b`, 'i')])
+);
+
+const attributeRegexes = new Map(
+  obsoleteAttributes.map(attribute => [
+    attribute,
+    // Matches the attribute preceded by whitespace anywhere in a tag, without
+    // requiring it to be the last attribute before the closing bracket.
+    new RegExp(`<[^>]*\\s${attribute}\\b(\\s*=\\s*(?:"[^"]*"|'[^']*'|[^"'\\s>]+))?`, 'i'),
+  ])
+);
+
+/**
+ * Check an HTML string for obsolete or proprietary elements and attributes.
+ *
+ * @param {string} html
+ * @returns {{ elements: string[], attributes: string[] }}
+ */
+export function checkMarkup(html) {
+  if (typeof html !== 'string') throw new TypeError('`html` must be a string');
+
+  const elements = [];
+  const attributes = [];
+
+  for (const [element, regex] of elementRegexes) {
+    if (regex.test(html)) elements.push(element);
+  }
+
+  for (const [attribute, regex] of attributeRegexes) {
+    if (regex.test(html)) attributes.push(attribute);
+  }
+
+  return { elements, attributes };
+}

package/src/index.test.ts

@@ -0,0 +1,25 @@
+/**
+ * TypeScript type definition tests
+ *
+ * This file is compiled by TypeScript during testing to verify that the
+ * declaration file is valid and types are correctly exported and usable.
+ *
+ * This file is not executed—it only needs to type-check successfully.
+ */
+
+import { checkMarkup, obsoleteElements, obsoleteAttributes } from './index.js';
+
+// Exported arrays are readonly string arrays
+const els: readonly string[] = obsoleteElements;
+const attrs: readonly string[] = obsoleteAttributes;
+
+// `checkMarkup` accepts a string and returns the correct shape
+const result: { elements: string[]; attributes: string[] } = checkMarkup('<center>test</center>');
+
+// `checkMarkup` rejects non-string input
+// @ts-expect-error
+checkMarkup(null);
+// @ts-expect-error
+checkMarkup(42);
+
+export { els, attrs, result };

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "include": [
+    "src/index.test.ts"
+  ],
+  "compilerOptions": {
+    "module": "nodenext",
+    "target": "esnext",
+    "noEmit": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "forceConsistentCasingInFileNames": true
+  }
+}