aiseo-audit 1.4.4 → 1.4.5
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 +43 -23
- 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
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
[](https://opensource.org/licenses/MIT)
|
|
6
6
|
[](https://nodejs.org)
|
|
7
7
|
[](https://www.typescriptlang.org/)
|
|
8
|
-
[](https://github.com/agencyenterprise/aiseo-audit)
|
|
9
9
|
[](https://codecov.io/gh/agencyenterprise/aiseo-audit)
|
|
10
10
|
|
|
11
11
|
<div align="center">
|
|
@@ -80,10 +80,13 @@ aiseo-audit https://example.com --md
|
|
|
80
80
|
# HTML report (Lighthouse-style)
|
|
81
81
|
aiseo-audit https://example.com --html
|
|
82
82
|
|
|
83
|
-
# Write
|
|
83
|
+
# Write to a file — format is inferred from the extension automatically
|
|
84
|
+
aiseo-audit https://example.com --out report.html
|
|
85
|
+
aiseo-audit https://example.com --out report.md
|
|
86
|
+
aiseo-audit https://example.com --out report.json
|
|
87
|
+
|
|
88
|
+
# Explicit format flag still works and takes precedence
|
|
84
89
|
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
90
|
|
|
88
91
|
# CI/CD: fail if score below threshold
|
|
89
92
|
aiseo-audit https://example.com --fail-under 70
|
|
@@ -119,22 +122,24 @@ jobs:
|
|
|
119
122
|
|
|
120
123
|
## CLI Options
|
|
121
124
|
|
|
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
|
|
125
|
+
| Option | Description | Default |
|
|
126
|
+
| ---------------------- | --------------------------------------------------------------------------------- | --------------------------------------------- |
|
|
127
|
+
| `[url]` | URL to audit | - |
|
|
128
|
+
| `--sitemap <url>` | Audit all URLs in a sitemap.xml | - |
|
|
129
|
+
| `--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 |
|
|
130
|
+
| `--json` | Output as JSON | - |
|
|
131
|
+
| `--md` | Output as Markdown | - |
|
|
132
|
+
| `--html` | Output as HTML | - |
|
|
133
|
+
| `--out <path>` | Write output to a file; format is inferred from `.html`, `.md`, `.json` extension | - |
|
|
134
|
+
| `--fail-under <n>` | Exit with code 1 if score < threshold | - |
|
|
135
|
+
| `--timeout <ms>` | Request timeout in ms | `45000` |
|
|
136
|
+
| `--user-agent <ua>` | Custom User-Agent string | `AISEOAudit/<version>` |
|
|
137
|
+
| `--config <path>` | Path to config file | - |
|
|
135
138
|
|
|
136
139
|
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
140
|
|
|
141
|
+
When `--out` is provided, the format is automatically inferred from the file extension (`.html` → HTML, `.md` → Markdown, `.json` → JSON) so you don't need to pass a separate format flag. An explicit `--html`, `--md`, or `--json` flag takes precedence if provided.
|
|
142
|
+
|
|
138
143
|
## Site-Wide Auditing
|
|
139
144
|
|
|
140
145
|
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.
|
|
@@ -145,8 +150,8 @@ By default, domain signals are fetched from the directory that contains the site
|
|
|
145
150
|
# Audit all URLs in a sitemap
|
|
146
151
|
aiseo-audit --sitemap https://example.com/sitemap.xml
|
|
147
152
|
|
|
148
|
-
# With HTML output
|
|
149
|
-
aiseo-audit --sitemap https://example.com/sitemap.xml --
|
|
153
|
+
# With HTML output — format inferred from extension
|
|
154
|
+
aiseo-audit --sitemap https://example.com/sitemap.xml --out report.html
|
|
150
155
|
|
|
151
156
|
# Override where domain signals are fetched from
|
|
152
157
|
aiseo-audit --sitemap https://example.com/projects/sitemap.xml --signals-base https://example.com
|
|
@@ -224,19 +229,19 @@ The audit evaluates 7 categories of AI search readiness (_[Detailed Breakdown he
|
|
|
224
229
|
|
|
225
230
|
### Pretty (default)
|
|
226
231
|
|
|
227
|
-
Color-coded terminal output with scores, factor breakdowns, and
|
|
232
|
+
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
233
|
|
|
229
234
|
### JSON
|
|
230
235
|
|
|
231
|
-
Full structured output with all scores, factor details, raw data, and recommendations. Best for integrations, CI/CD pipelines, and programmatic consumption.
|
|
236
|
+
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
237
|
|
|
233
238
|
### Markdown
|
|
234
239
|
|
|
235
|
-
Structured report with category tables, factor details, and recommendations grouped by category. Best for documentation, PRs, and sharing.
|
|
240
|
+
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
241
|
|
|
237
242
|
### HTML
|
|
238
243
|
|
|
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.
|
|
244
|
+
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.
|
|
240
245
|
|
|
241
246
|
## Config File
|
|
242
247
|
|
|
@@ -300,6 +305,21 @@ import type {
|
|
|
300
305
|
} from "aiseo-audit";
|
|
301
306
|
```
|
|
302
307
|
|
|
308
|
+
`RecommendationType` includes the base fields (`category`, `factor`, `currentValue`, `priority`, `recommendation`) plus three optional fields populated for high-impact factors:
|
|
309
|
+
|
|
310
|
+
```typescript
|
|
311
|
+
type RecommendationType = {
|
|
312
|
+
category: string;
|
|
313
|
+
factor: string;
|
|
314
|
+
currentValue: string;
|
|
315
|
+
priority: "high" | "medium" | "low";
|
|
316
|
+
recommendation: string;
|
|
317
|
+
steps?: string[]; // ordered implementation steps
|
|
318
|
+
codeExample?: string; // ready-to-use code snippet
|
|
319
|
+
learnMoreUrl?: string; // link to canonical spec or docs
|
|
320
|
+
};
|
|
321
|
+
```
|
|
322
|
+
|
|
303
323
|
## Philosophy
|
|
304
324
|
|
|
305
325
|
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.
|