aiseo-audit 1.4.4 → 1.4.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +134 -49
- package/dist/cli.js +866 -133
- package/dist/cli.mjs +866 -133
- package/dist/index.d.mts +12 -0
- package/dist/index.d.ts +12 -0
- package/dist/index.js +862 -132
- package/dist/index.mjs +862 -132
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,22 +1,26 @@
|
|
|
1
1
|
# aiseo-audit
|
|
2
2
|
|
|
3
3
|
[](https://www.npmjs.com/package/aiseo-audit)
|
|
4
|
+
[](https://www.npmjs.com/package/aiseo-audit)
|
|
4
5
|
[](https://www.npmjs.com/package/aiseo-audit)
|
|
5
6
|
[](https://opensource.org/licenses/MIT)
|
|
6
7
|
[](https://nodejs.org)
|
|
7
8
|
[](https://www.typescriptlang.org/)
|
|
8
|
-
[](https://github.com/agencyenterprise/aiseo-audit)
|
|
9
10
|
[](https://codecov.io/gh/agencyenterprise/aiseo-audit)
|
|
11
|
+
[](https://github.com/agencyenterprise/aiseo-audit/stargazers)
|
|
10
12
|
|
|
11
13
|
<div align="center">
|
|
12
|
-
<strong>Testing
|
|
13
|
-
<img src="docs/assets/ai-seo-bad-site-example.gif" alt="Testing
|
|
14
|
+
<strong>Testing example</strong><br /><br />
|
|
15
|
+
<img src="docs/assets/ai-seo-bad-site-example.gif" alt="Testing example" width="600" />
|
|
14
16
|
</div>
|
|
15
17
|
|
|
16
18
|
Deterministic CLI that audits web pages for **AI search readiness**. Think Lighthouse, but for how well AI engines can fetch, extract, understand, and cite your content.
|
|
17
19
|
|
|
18
20
|
**AI SEO measures how reusable your content is for generative engines, not traditional search rankings.**
|
|
19
21
|
|
|
22
|
+
**Who is this for?** Content teams running pre-publish checks, developers gating deployments in CI/CD, and marketers auditing their own or competitor pages. If your content needs to be cited (not just ranked), this tool tells you where you stand.
|
|
23
|
+
|
|
20
24
|
- [Quick Start](#quick-start)
|
|
21
25
|
- [CI/CD](#cicd)
|
|
22
26
|
- [CLI Options](#cli-options)
|
|
@@ -50,7 +54,7 @@ aiseo-audit goes deeper:
|
|
|
50
54
|
## Quick Start
|
|
51
55
|
|
|
52
56
|
```bash
|
|
53
|
-
# Try it instantly
|
|
57
|
+
# Try it instantly, no install required
|
|
54
58
|
npx aiseo-audit https://yoursite.com
|
|
55
59
|
```
|
|
56
60
|
|
|
@@ -80,10 +84,13 @@ aiseo-audit https://example.com --md
|
|
|
80
84
|
# HTML report (Lighthouse-style)
|
|
81
85
|
aiseo-audit https://example.com --html
|
|
82
86
|
|
|
83
|
-
# Write
|
|
87
|
+
# Write to a file, format is inferred from the extension automatically
|
|
88
|
+
aiseo-audit https://example.com --out report.html
|
|
89
|
+
aiseo-audit https://example.com --out report.md
|
|
90
|
+
aiseo-audit https://example.com --out report.json
|
|
91
|
+
|
|
92
|
+
# Explicit format flag still works and takes precedence
|
|
84
93
|
aiseo-audit https://example.com --html --out report.html
|
|
85
|
-
aiseo-audit https://example.com --md --out report.md
|
|
86
|
-
aiseo-audit https://example.com --json --out report.json
|
|
87
94
|
|
|
88
95
|
# CI/CD: fail if score below threshold
|
|
89
96
|
aiseo-audit https://example.com --fail-under 70
|
|
@@ -117,40 +124,63 @@ jobs:
|
|
|
117
124
|
- run: npx aiseo-audit https://yoursite.com --fail-under 70
|
|
118
125
|
```
|
|
119
126
|
|
|
127
|
+
**Using a preview deployment URL?** If your CI pipeline produces a dynamic URL (e.g. a Vercel or Netlify preview), capture it from a prior step and pass it in:
|
|
128
|
+
|
|
129
|
+
```yaml
|
|
130
|
+
jobs:
|
|
131
|
+
deploy-and-audit:
|
|
132
|
+
runs-on: ubuntu-latest
|
|
133
|
+
steps:
|
|
134
|
+
- name: Deploy to preview
|
|
135
|
+
id: deploy
|
|
136
|
+
run: echo "url=https://your-preview-url.vercel.app" >> $GITHUB_OUTPUT
|
|
137
|
+
# Replace the above with your actual deploy step that outputs a URL
|
|
138
|
+
|
|
139
|
+
- name: Run AI SEO Audit
|
|
140
|
+
run: npx aiseo-audit ${{ steps.deploy.outputs.url }} --fail-under 70
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
The `--fail-under` threshold sets the minimum acceptable score. Exit code `1` is returned when the score falls below it, which GitHub Actions treats as a failed step.
|
|
144
|
+
|
|
120
145
|
## CLI Options
|
|
121
146
|
|
|
122
|
-
| Option | Description
|
|
123
|
-
| ---------------------- |
|
|
124
|
-
| `[url]` | URL to audit
|
|
125
|
-
| `--sitemap <url>` | Audit all URLs in a sitemap.xml
|
|
126
|
-
| `--signals-base <url>` | Base URL to fetch domain signals from (robots.txt, llms.txt, llms-full.txt)
|
|
127
|
-
| `--json` | Output as JSON
|
|
128
|
-
| `--md` | Output as Markdown
|
|
129
|
-
| `--html` | Output as HTML
|
|
130
|
-
| `--out <path>` | Write
|
|
131
|
-
| `--fail-under <n>` | Exit with code 1 if score < threshold
|
|
132
|
-
| `--timeout <ms>` | Request timeout in ms
|
|
133
|
-
| `--user-agent <ua>` | Custom User-Agent string
|
|
134
|
-
| `--config <path>` | Path to config file
|
|
147
|
+
| Option | Description | Default |
|
|
148
|
+
| ---------------------- | --------------------------------------------------------------------------------- | --------------------------------------------- |
|
|
149
|
+
| `[url]` | URL to audit | - |
|
|
150
|
+
| `--sitemap <url>` | Audit all URLs in a sitemap.xml | - |
|
|
151
|
+
| `--signals-base <url>` | Base URL to fetch domain signals from (robots.txt, llms.txt, llms-full.txt) | Directory of the URL or sitemap being audited |
|
|
152
|
+
| `--json` | Output as JSON | - |
|
|
153
|
+
| `--md` | Output as Markdown | - |
|
|
154
|
+
| `--html` | Output as HTML | - |
|
|
155
|
+
| `--out <path>` | Write output to a file; format is inferred from `.html`, `.md`, `.json` extension | - |
|
|
156
|
+
| `--fail-under <n>` | Exit with code 1 if score < threshold | - |
|
|
157
|
+
| `--timeout <ms>` | Request timeout in ms | `45000` |
|
|
158
|
+
| `--user-agent <ua>` | Custom User-Agent string | `AISEOAudit/<version>` |
|
|
159
|
+
| `--config <path>` | Path to config file | - |
|
|
135
160
|
|
|
136
161
|
Either `[url]` or `--sitemap` must be provided, but not both. If no output flag is given, the default is `pretty` (color-coded terminal output). The default format can also be set in the config file.
|
|
137
162
|
|
|
163
|
+
When `--out` is provided, the format is automatically inferred from the file extension (`.html` becomes HTML, `.md` becomes Markdown, `.json` becomes JSON) so you don't need to pass a separate format flag. An explicit `--html`, `--md`, or `--json` flag takes precedence if provided.
|
|
164
|
+
|
|
138
165
|
## Site-Wide Auditing
|
|
139
166
|
|
|
140
|
-
Use `--sitemap` to audit every URL in a `sitemap.xml`. Domain signals (`robots.txt`, `llms.txt`, `llms-full.txt`) are fetched once and shared across all URL audits
|
|
167
|
+
Use `--sitemap` to audit every URL in a `sitemap.xml`. Domain signals (`robots.txt`, `llms.txt`, `llms-full.txt`) are fetched once and shared across all URL audits, not re-fetched per page.
|
|
141
168
|
|
|
142
|
-
By default, domain signals are fetched from the directory that contains the sitemap file. For example, if your sitemap is at `https://example.com/projects/sitemap.xml`, signals are fetched from `https://example.com/projects/`
|
|
169
|
+
By default, domain signals are fetched from the directory that contains the sitemap file. For example, if your sitemap is at `https://example.com/projects/sitemap.xml`, signals are fetched from `https://example.com/projects/` so the tool checks `https://example.com/projects/robots.txt`, `https://example.com/projects/llms.txt`, and `https://example.com/projects/llms-full.txt`. If your signals live at the domain root instead, use `--signals-base` to specify the correct location explicitly.
|
|
143
170
|
|
|
144
171
|
```bash
|
|
145
172
|
# Audit all URLs in a sitemap
|
|
146
173
|
aiseo-audit --sitemap https://example.com/sitemap.xml
|
|
147
174
|
|
|
148
|
-
# With HTML output
|
|
149
|
-
aiseo-audit --sitemap https://example.com/sitemap.xml --
|
|
175
|
+
# With HTML output, format inferred from extension
|
|
176
|
+
aiseo-audit --sitemap https://example.com/sitemap.xml --out report.html
|
|
150
177
|
|
|
151
|
-
# Override where domain signals are fetched from
|
|
178
|
+
# Override where domain signals are fetched from (sitemap)
|
|
152
179
|
aiseo-audit --sitemap https://example.com/projects/sitemap.xml --signals-base https://example.com
|
|
153
180
|
|
|
181
|
+
# Override where domain signals are fetched from (single URL)
|
|
182
|
+
aiseo-audit https://example.com/projects/page --signals-base https://example.com
|
|
183
|
+
|
|
154
184
|
# Fail if average score across all URLs is below threshold
|
|
155
185
|
aiseo-audit --sitemap https://example.com/sitemap.xml --fail-under 70
|
|
156
186
|
```
|
|
@@ -161,21 +191,7 @@ The sitemap report includes:
|
|
|
161
191
|
- **Site-wide category averages**: identify which audit categories are weakest across your whole site
|
|
162
192
|
- **Per-URL results**: individual score, grade, and top recommendation for each URL
|
|
163
193
|
|
|
164
|
-
Sitemap index files (sitemaps that reference other sitemaps) are supported
|
|
165
|
-
|
|
166
|
-
### `--signals-base`
|
|
167
|
-
|
|
168
|
-
By default, domain signals are fetched from the directory containing the page or sitemap being audited — not necessarily the domain root. Use `--signals-base` to explicitly set where `robots.txt`, `llms.txt`, and `llms-full.txt` are fetched from:
|
|
169
|
-
|
|
170
|
-
```bash
|
|
171
|
-
# Single URL: fetch signals from a specific base
|
|
172
|
-
aiseo-audit https://example.com/projects/page --signals-base https://example.com
|
|
173
|
-
|
|
174
|
-
# Sitemap: same override applies to all URLs in the sitemap
|
|
175
|
-
aiseo-audit --sitemap https://example.com/projects/sitemap.xml --signals-base https://example.com
|
|
176
|
-
```
|
|
177
|
-
|
|
178
|
-
Every report format explicitly shows which URL domain signals were fetched from, so there is no guesswork about where `robots.txt`, `llms.txt`, and `llms-full.txt` were checked.
|
|
194
|
+
Sitemap index files (sitemaps that reference other sitemaps) are supported, and all child sitemaps are fetched and flattened automatically. Every report format explicitly shows which URL domain signals were fetched from, so there is no guesswork about where `robots.txt`, `llms.txt`, and `llms-full.txt` were checked.
|
|
179
195
|
|
|
180
196
|
## User Agent
|
|
181
197
|
|
|
@@ -220,23 +236,41 @@ The audit evaluates 7 categories of AI search readiness (_[Detailed Breakdown he
|
|
|
220
236
|
| **Authority Context** | Is there author attribution, organization identity, publish dates, and structured data? |
|
|
221
237
|
| **Readability for Compression** | Is the content written at a readability level that compresses well for AI summarization? |
|
|
222
238
|
|
|
239
|
+
### Interpreting Your Score
|
|
240
|
+
|
|
241
|
+
| Score | Grade | What It Means |
|
|
242
|
+
| ------ | ----- | -------------------------------------------------------------------------------------------------------- |
|
|
243
|
+
| 90–100 | A | Highly optimized. AI engines can fetch, understand, and cite your content with minimal friction. |
|
|
244
|
+
| 75–89 | B | Good foundation. A few targeted improvements will push you into the top tier. |
|
|
245
|
+
| 60–74 | C | Moderate readiness. Structural or content gaps are likely limiting your citation potential. |
|
|
246
|
+
| 40–59 | D | Significant gaps. Core signals (structure, answerability, authority) need attention. |
|
|
247
|
+
| 0–39 | F | Not AI-ready. Start with Content Extractability. If the content cannot be fetched, nothing else matters. |
|
|
248
|
+
|
|
249
|
+
The per-category breakdown in each report shows exactly where to focus. Start with high-priority recommendations in your lowest-scoring categories.
|
|
250
|
+
|
|
223
251
|
## Output Formats
|
|
224
252
|
|
|
225
253
|
### Pretty (default)
|
|
226
254
|
|
|
227
|
-
Color-coded terminal output with scores, factor breakdowns, and
|
|
255
|
+
Color-coded terminal output with scores, factor breakdowns, and recommendations. Where available, recommendations include numbered implementation steps, a ready-to-use code example, and a learn more link. Best for quick checks during development.
|
|
228
256
|
|
|
229
257
|
### JSON
|
|
230
258
|
|
|
231
|
-
Full structured output with all scores, factor details, raw data, and recommendations. Best for integrations, CI/CD pipelines, and programmatic consumption.
|
|
259
|
+
Full structured output with all scores, factor details, raw data, and recommendations. Recommendations include optional `steps`, `codeExample`, and `learnMoreUrl` fields where applicable. Best for integrations, CI/CD pipelines, and programmatic consumption.
|
|
232
260
|
|
|
233
261
|
### Markdown
|
|
234
262
|
|
|
235
|
-
Structured report with category tables, factor details, and recommendations grouped by category. Best for documentation, PRs, and sharing.
|
|
263
|
+
Structured report with category tables, factor details, and recommendations grouped by category. Recommendations with steps render as numbered lists; code examples render as fenced code blocks. Best for documentation, PRs, and sharing.
|
|
236
264
|
|
|
237
265
|
### HTML
|
|
238
266
|
|
|
239
|
-
Self-contained single-file report with SVG score gauges, color-coded sections, and recommendations grouped by category. Best for stakeholder reports and visual review.
|
|
267
|
+
Self-contained single-file report with SVG score gauges, color-coded sections, and recommendations grouped by category. Recommendations with steps and code examples render as inline detail sections below each recommendation row. Best for stakeholder reports and visual review.
|
|
268
|
+
|
|
269
|
+
```bash
|
|
270
|
+
aiseo-audit https://example.com --out report.html
|
|
271
|
+
```
|
|
272
|
+
|
|
273
|
+
> **Tip:** Run this against your own site and open the file in a browser to get the most actionable view of where to focus. The HTML report is the closest equivalent to Lighthouse's output.
|
|
240
274
|
|
|
241
275
|
## Config File
|
|
242
276
|
|
|
@@ -265,7 +299,43 @@ You can also pass an explicit path with `--config path/to/config.json`.
|
|
|
265
299
|
}
|
|
266
300
|
```
|
|
267
301
|
|
|
268
|
-
Weights are relative. Set a category to `2` to double its importance, or `0` to exclude it.
|
|
302
|
+
Weights are relative. Set a category to `2` to double its importance, or `0` to exclude it entirely from scoring.
|
|
303
|
+
|
|
304
|
+
**Example: tuning for a blog or editorial site.** Content that needs to be cited by AI engines should be highly answerable and readable. Double those weights and reduce the emphasis on domain-signal files (`authorityContext` covers schema markup, while `groundingSignals` covers citations and statistics):
|
|
305
|
+
|
|
306
|
+
```json
|
|
307
|
+
{
|
|
308
|
+
"format": "html",
|
|
309
|
+
"failUnder": 65,
|
|
310
|
+
"weights": {
|
|
311
|
+
"contentExtractability": 2,
|
|
312
|
+
"contentStructure": 1,
|
|
313
|
+
"answerability": 2,
|
|
314
|
+
"entityClarity": 1,
|
|
315
|
+
"groundingSignals": 2,
|
|
316
|
+
"authorityContext": 1,
|
|
317
|
+
"readabilityForCompression": 2
|
|
318
|
+
}
|
|
319
|
+
}
|
|
320
|
+
```
|
|
321
|
+
|
|
322
|
+
**Example: tuning for a product or docs site.** Authority and structure matter more when content needs to be trusted and navigable:
|
|
323
|
+
|
|
324
|
+
```json
|
|
325
|
+
{
|
|
326
|
+
"format": "html",
|
|
327
|
+
"failUnder": 70,
|
|
328
|
+
"weights": {
|
|
329
|
+
"contentExtractability": 2,
|
|
330
|
+
"contentStructure": 2,
|
|
331
|
+
"answerability": 1,
|
|
332
|
+
"entityClarity": 1,
|
|
333
|
+
"groundingSignals": 1,
|
|
334
|
+
"authorityContext": 2,
|
|
335
|
+
"readabilityForCompression": 1
|
|
336
|
+
}
|
|
337
|
+
}
|
|
338
|
+
```
|
|
269
339
|
|
|
270
340
|
## Programmatic API
|
|
271
341
|
|
|
@@ -300,6 +370,21 @@ import type {
|
|
|
300
370
|
} from "aiseo-audit";
|
|
301
371
|
```
|
|
302
372
|
|
|
373
|
+
`RecommendationType` includes the base fields (`category`, `factor`, `currentValue`, `priority`, `recommendation`) plus three optional fields populated for high-impact factors:
|
|
374
|
+
|
|
375
|
+
```typescript
|
|
376
|
+
type RecommendationType = {
|
|
377
|
+
category: string;
|
|
378
|
+
factor: string;
|
|
379
|
+
currentValue: string;
|
|
380
|
+
priority: "high" | "medium" | "low";
|
|
381
|
+
recommendation: string;
|
|
382
|
+
steps?: string[]; // ordered implementation steps
|
|
383
|
+
codeExample?: string; // ready-to-use code snippet
|
|
384
|
+
learnMoreUrl?: string; // link to canonical spec or docs
|
|
385
|
+
};
|
|
386
|
+
```
|
|
387
|
+
|
|
303
388
|
## Philosophy
|
|
304
389
|
|
|
305
390
|
This tool measures **AI search reusability**: how well a page's content can be fetched, extracted, understood, and reused by AI engines like ChatGPT, Claude, Perplexity, and Gemini.
|
|
@@ -321,13 +406,13 @@ It is:
|
|
|
321
406
|
|
|
322
407
|
## Compatibility Notes
|
|
323
408
|
|
|
324
|
-
**Node.js**
|
|
409
|
+
**Node.js** - Requires Node 20 or later. The `engines` field in `package.json` enforces this. Earlier versions will produce runtime errors.
|
|
325
410
|
|
|
326
|
-
**Zod**
|
|
411
|
+
**Zod** - Uses [Zod 4](https://zod.dev). If you consume the library API and also use Zod in your project, ensure you are on Zod 4+ to avoid type incompatibilities.
|
|
327
412
|
|
|
328
|
-
**CJS bin entry**
|
|
413
|
+
**CJS bin entry** - The `bin/aiseo-audit.js` executable uses `require()` (CommonJS). This is compatible with all Node 20+ environments regardless of your project's module system. The library exports support both ESM (`import`) and CJS (`require`).
|
|
329
414
|
|
|
330
|
-
**Config discovery**
|
|
415
|
+
**Config discovery** - When using the programmatic API, `loadConfig()` searches for config files starting from `process.cwd()`. If your application's working directory differs from where your config file lives, pass an explicit path:
|
|
331
416
|
|
|
332
417
|
```typescript
|
|
333
418
|
const config = await loadConfig("/path/to/aiseo.config.json");
|