vouchington-tooling 0.81.0 → 0.83.0
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 +87 -0
- package/dist/ast-grep-config-parity/check.d.mts +37 -0
- package/dist/ast-grep-config-parity/check.mjs +131 -0
- package/dist/ast-grep-config-parity/discover.d.mts +31 -0
- package/dist/ast-grep-config-parity/discover.mjs +50 -0
- package/dist/ast-grep-config-parity/index.d.mts +2 -0
- package/dist/ast-grep-config-parity/index.mjs +2 -0
- package/dist/markdown-article-links/check.d.mts +30 -0
- package/dist/markdown-article-links/check.mjs +68 -0
- package/dist/markdown-article-links/discover.d.mts +18 -0
- package/dist/markdown-article-links/discover.mjs +29 -0
- package/dist/markdown-article-links/index.d.mts +2 -0
- package/dist/markdown-article-links/index.mjs +2 -0
- package/package.json +11 -1
- package/scripts/__pycache__/run_bounded_process.cpython-314.pyc +0 -0
package/README.md
CHANGED
|
@@ -675,6 +675,14 @@ import {
|
|
|
675
675
|
parseGfmMarkdown,
|
|
676
676
|
parseMarkdownTables,
|
|
677
677
|
} from 'vouchington-tooling/markdown'
|
|
678
|
+
import {
|
|
679
|
+
checkMarkdownArticleLinks,
|
|
680
|
+
discoverMarkdownArticles,
|
|
681
|
+
} from 'vouchington-tooling/markdown-article-links'
|
|
682
|
+
import {
|
|
683
|
+
checkAstGrepConfigParity,
|
|
684
|
+
discoverAstGrepConfig,
|
|
685
|
+
} from 'vouchington-tooling/ast-grep-config-parity'
|
|
678
686
|
import { readResponseBody } from 'vouchington-tooling/http-body'
|
|
679
687
|
import { runAstGrepRule } from 'vouchington-tooling/ast-grep-rule'
|
|
680
688
|
import { parseReviewPayload, remapReviewComments } from 'vouchington-tooling/gha-review-payload'
|
|
@@ -789,6 +797,85 @@ exceedsLargeDiffThreshold(countDiffLineChanges(diffText), {
|
|
|
789
797
|
})
|
|
790
798
|
```
|
|
791
799
|
|
|
800
|
+
`vouchington-tooling/ast-grep-config-parity` checks an ast-grep setup against the rule pack it loads
|
|
801
|
+
at run time. The checker does no I/O; the discovery adapter reads the files.
|
|
802
|
+
|
|
803
|
+
```ts
|
|
804
|
+
const input = await discoverAstGrepConfig(process.cwd(), {
|
|
805
|
+
localRuleDir: 'ast-grep-rules',
|
|
806
|
+
packRulesDir: 'node_modules/some-pack/rules',
|
|
807
|
+
})
|
|
808
|
+
const offenders = checkAstGrepConfigParity({
|
|
809
|
+
...input,
|
|
810
|
+
languageExceptions: { 'data/json-rule.yml': 'Json' },
|
|
811
|
+
})
|
|
812
|
+
// [{ name: 'copy.yml', reason: 'copied-pack-rule', detail: '…' }]
|
|
813
|
+
```
|
|
814
|
+
|
|
815
|
+
`checkAstGrepConfigParity({ sgconfig, localRuleDir, localRules, packRulePaths, expectedLanguageGlobs,
|
|
816
|
+
defaultLanguage, languageExceptions })` is synchronous and returns offenders `{ name, reason, detail }`.
|
|
817
|
+
`sgconfig` is `{ name, source }` (raw YAML), `localRules` is `{ path, source }[]` with paths relative to
|
|
818
|
+
`localRuleDir`, and `packRulePaths` are relative to the pack rules directory. `expectedLanguageGlobs`
|
|
819
|
+
defaults to `{ Tsx: ['**/*.ts', '**/*.mts', '**/*.cts', '**/*.tsx'] }`, `defaultLanguage` to `'Tsx'`
|
|
820
|
+
and `languageExceptions` (rule path to language) to `{}`. Reasons:
|
|
821
|
+
|
|
822
|
+
- `rule-dirs`: `ruleDirs` does not deep-equal `[localRuleDir]`. The pack directory is added at run
|
|
823
|
+
time, not committed.
|
|
824
|
+
- `language-globs`: `languageGlobs` does not deep-equal `expectedLanguageGlobs` as a whole object.
|
|
825
|
+
- `copied-pack-rule`: a local rule's relative path, or its basename, matches a pack rule's relative
|
|
826
|
+
path or basename, so a copy is caught whether or not the directory layout matches.
|
|
827
|
+
- `empty-local-rules`: no local rules were provided.
|
|
828
|
+
- `rule-language`: a rule's `language` differs from its exception's language, or from
|
|
829
|
+
`defaultLanguage` when none is listed. Every `---` document in a rule file is checked and each
|
|
830
|
+
mismatch is reported with its document index; an empty file counts as a missing `language`. A
|
|
831
|
+
missing `language` is an offender. An exception that names
|
|
832
|
+
no local rule is reported too, so a stale exception cannot hide.
|
|
833
|
+
- `tsx-companion`: a local rule path matches `-tsx.yml` or `-tsx.yaml`.
|
|
834
|
+
- `invalid-yaml`: `sgconfig` or a local rule does not parse. Other checks on that file are skipped.
|
|
835
|
+
|
|
836
|
+
`discoverAstGrepConfig(root, { localRuleDir, sgconfigPath, packRulesDir, allowEmpty, listTrackedFiles })`
|
|
837
|
+
returns the checker's inputs. It reads `sgconfigPath` (default `sgconfig.yml`) and the git-tracked
|
|
838
|
+
`*.yml` and `*.yaml` files under `localRuleDir`, recursively, through `git ls-files -z` with an argv
|
|
839
|
+
array and no shell, so untracked files are ignored. `packRulesDir` is listed from the filesystem
|
|
840
|
+
because the installed pack is not tracked. Paths are sorted by code unit. Empty local discovery
|
|
841
|
+
throws unless `allowEmpty` is set; an empty pack directory always throws, so a wrong `packRulesDir`
|
|
842
|
+
cannot pass. `listTrackedFiles(root, dir)` replaces the git runner, for example in tests.
|
|
843
|
+
|
|
844
|
+
`vouchington-tooling/markdown-article-links` checks rendered article links statically. It bundles no
|
|
845
|
+
markdown parser or renderer: the caller supplies all three callbacks.
|
|
846
|
+
|
|
847
|
+
```ts
|
|
848
|
+
const inputs = await discoverMarkdownArticles('content/articles')
|
|
849
|
+
const offenders = await checkMarkdownArticleLinks({
|
|
850
|
+
inputs,
|
|
851
|
+
routePrefix: '/article/',
|
|
852
|
+
parse: (source) => ({ slug: frontmatter(source).slug, body: bodyOf(source) }),
|
|
853
|
+
rewrite: rewriteArticleLinks,
|
|
854
|
+
render: renderMarkdown, // may return a Promise
|
|
855
|
+
})
|
|
856
|
+
// [{ name: 'a.md', href: '/article/gone', reason: 'missing-target' }]
|
|
857
|
+
```
|
|
858
|
+
|
|
859
|
+
`checkMarkdownArticleLinks({ inputs, routePrefix, parse, rewrite, render })` takes
|
|
860
|
+
`inputs: { name, source }[]` and derives each slug as `slug || basename(name, '.md')`. It renders
|
|
861
|
+
`rewrite(body)` for each input and reads every `href="…"` from the HTML. Hrefs with a scheme or a
|
|
862
|
+
leading `//` are skipped. For the rest it strips the query and fragment, then returns offenders
|
|
863
|
+
`{ name, href, reason }`:
|
|
864
|
+
|
|
865
|
+
- `residual-md`: the path still ends in `.md`.
|
|
866
|
+
- `missing-target`: the path is exactly `<routePrefix><slug>` with no further `/`, and no input
|
|
867
|
+
provides that slug.
|
|
868
|
+
- `duplicate-slug`: two or more inputs resolve to the same slug. Every such input is reported, with
|
|
869
|
+
the shared slug as `href`.
|
|
870
|
+
|
|
871
|
+
`discoverMarkdownArticles(root, { exclude, allowEmpty, listTrackedFiles })` returns the inputs. It
|
|
872
|
+
runs `git ls-files -z -- '*.md'` from `root` with an argv array and no shell, so only git-tracked
|
|
873
|
+
files count: untracked files are ignored. Only files directly under `root` are used; nested
|
|
874
|
+
directories are never searched. `README.md` is excluded by default, and `exclude` replaces that list
|
|
875
|
+
with the basenames you give it. The result is sorted by name (code-unit order). If nothing is found
|
|
876
|
+
it throws, because a wrong `root` must not pass silently; pass `allowEmpty: true` to get `[]`
|
|
877
|
+
instead. `listTrackedFiles(root)` replaces the git runner, for example in tests.
|
|
878
|
+
|
|
792
879
|
This breaking minor removes `getDiffAgainstBase`; migrate callers to `processDiffCommand` and pass
|
|
793
880
|
the command they need to run.
|
|
794
881
|
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
export type AstGrepConfigParityReason = 'rule-dirs' | 'language-globs' | 'copied-pack-rule' | 'empty-local-rules' | 'rule-language' | 'tsx-companion' | 'invalid-yaml';
|
|
2
|
+
export interface AstGrepConfigParityOffender {
|
|
3
|
+
/** The offending file (or the stale exception path). */
|
|
4
|
+
name: string;
|
|
5
|
+
reason: AstGrepConfigParityReason;
|
|
6
|
+
detail: string;
|
|
7
|
+
}
|
|
8
|
+
export interface AstGrepConfigParityFile {
|
|
9
|
+
path: string;
|
|
10
|
+
source: string;
|
|
11
|
+
}
|
|
12
|
+
export interface CheckAstGrepConfigParityOptions {
|
|
13
|
+
sgconfig: {
|
|
14
|
+
name: string;
|
|
15
|
+
source: string;
|
|
16
|
+
};
|
|
17
|
+
/** The tracked local rule directory, for example `ast-grep-rules`. */
|
|
18
|
+
localRuleDir: string;
|
|
19
|
+
/** Local rule files, with paths relative to `localRuleDir`. */
|
|
20
|
+
localRules: readonly AstGrepConfigParityFile[];
|
|
21
|
+
/** Pack rule file paths, relative to the pack rules directory. */
|
|
22
|
+
packRulePaths: readonly string[];
|
|
23
|
+
/** Defaults to `DEFAULT_LANGUAGE_GLOBS`: the `Tsx` language over ts, mts, cts and tsx files. */
|
|
24
|
+
expectedLanguageGlobs?: Readonly<Record<string, readonly string[]>>;
|
|
25
|
+
/** Defaults to `Tsx`. */
|
|
26
|
+
defaultLanguage?: string;
|
|
27
|
+
/** Rule path (relative to `localRuleDir`) to its required language. Defaults to `{}`. */
|
|
28
|
+
languageExceptions?: Readonly<Record<string, string>>;
|
|
29
|
+
}
|
|
30
|
+
export declare const DEFAULT_LANGUAGE_GLOBS: Readonly<Record<string, readonly string[]>>;
|
|
31
|
+
type Out = AstGrepConfigParityOffender[];
|
|
32
|
+
/**
|
|
33
|
+
* Checks an ast-grep configuration against the shipped rule pack. Pure and synchronous: callers
|
|
34
|
+
* supply file contents (see `discoverAstGrepConfig`). Returns offenders; an empty array passes.
|
|
35
|
+
*/
|
|
36
|
+
export declare function checkAstGrepConfigParity(options: CheckAstGrepConfigParityOptions): Out;
|
|
37
|
+
export {};
|
|
@@ -0,0 +1,131 @@
|
|
|
1
|
+
import { posix } from 'node:path';
|
|
2
|
+
import { isDeepStrictEqual } from 'node:util';
|
|
3
|
+
import { parse, parseAllDocuments } from 'yaml';
|
|
4
|
+
export const DEFAULT_LANGUAGE_GLOBS = {
|
|
5
|
+
Tsx: ['**/*.ts', '**/*.mts', '**/*.cts', '**/*.tsx'],
|
|
6
|
+
};
|
|
7
|
+
const TSX_COMPANION = /-tsx\.ya?ml$/;
|
|
8
|
+
function tryParse(source) {
|
|
9
|
+
try {
|
|
10
|
+
return { ok: true, value: parse(source) };
|
|
11
|
+
}
|
|
12
|
+
catch (error) {
|
|
13
|
+
return { ok: false, message: error.message };
|
|
14
|
+
}
|
|
15
|
+
}
|
|
16
|
+
function field(value, key) {
|
|
17
|
+
return typeof value === 'object' && value !== null
|
|
18
|
+
? value[key]
|
|
19
|
+
: undefined;
|
|
20
|
+
}
|
|
21
|
+
function show(value) {
|
|
22
|
+
return JSON.stringify(value) ?? 'undefined';
|
|
23
|
+
}
|
|
24
|
+
function checkSgconfig(options, out) {
|
|
25
|
+
const { name, source } = options.sgconfig;
|
|
26
|
+
const parsed = tryParse(source);
|
|
27
|
+
if (!parsed.ok) {
|
|
28
|
+
out.push({ name, reason: 'invalid-yaml', detail: parsed.message });
|
|
29
|
+
return;
|
|
30
|
+
}
|
|
31
|
+
const ruleDirs = field(parsed.value, 'ruleDirs');
|
|
32
|
+
if (!isDeepStrictEqual(ruleDirs, [options.localRuleDir])) {
|
|
33
|
+
out.push({
|
|
34
|
+
name,
|
|
35
|
+
reason: 'rule-dirs',
|
|
36
|
+
detail: `ruleDirs is ${show(ruleDirs)}, expected ${show([options.localRuleDir])}`,
|
|
37
|
+
});
|
|
38
|
+
}
|
|
39
|
+
const expected = options.expectedLanguageGlobs ?? DEFAULT_LANGUAGE_GLOBS;
|
|
40
|
+
const globs = field(parsed.value, 'languageGlobs');
|
|
41
|
+
if (!isDeepStrictEqual(globs, expected)) {
|
|
42
|
+
out.push({
|
|
43
|
+
name,
|
|
44
|
+
reason: 'language-globs',
|
|
45
|
+
detail: `languageGlobs is ${show(globs)}, expected ${show(expected)}`,
|
|
46
|
+
});
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
function checkRuleLanguage(rule, expected, out) {
|
|
50
|
+
const documents = parseAllDocuments(rule.source);
|
|
51
|
+
const failed = documents.find((document) => document.errors.length > 0);
|
|
52
|
+
if (failed) {
|
|
53
|
+
out.push({ name: rule.path, reason: 'invalid-yaml', detail: failed.errors[0].message });
|
|
54
|
+
return;
|
|
55
|
+
}
|
|
56
|
+
if (documents.length === 0) {
|
|
57
|
+
out.push({
|
|
58
|
+
name: rule.path,
|
|
59
|
+
reason: 'rule-language',
|
|
60
|
+
detail: `language is undefined (no YAML documents), expected ${show(expected)}`,
|
|
61
|
+
});
|
|
62
|
+
}
|
|
63
|
+
let values;
|
|
64
|
+
try {
|
|
65
|
+
values = documents.map((document) => document.toJS());
|
|
66
|
+
}
|
|
67
|
+
catch (error) {
|
|
68
|
+
out.push({ name: rule.path, reason: 'invalid-yaml', detail: error.message });
|
|
69
|
+
return;
|
|
70
|
+
}
|
|
71
|
+
values.forEach((value, index) => {
|
|
72
|
+
const language = field(value, 'language');
|
|
73
|
+
if (language !== expected) {
|
|
74
|
+
out.push({
|
|
75
|
+
name: rule.path,
|
|
76
|
+
reason: 'rule-language',
|
|
77
|
+
detail: `document ${index}: language is ${show(language)}, expected ${show(expected)}`,
|
|
78
|
+
});
|
|
79
|
+
}
|
|
80
|
+
});
|
|
81
|
+
}
|
|
82
|
+
/**
|
|
83
|
+
* Checks an ast-grep configuration against the shipped rule pack. Pure and synchronous: callers
|
|
84
|
+
* supply file contents (see `discoverAstGrepConfig`). Returns offenders; an empty array passes.
|
|
85
|
+
*/
|
|
86
|
+
export function checkAstGrepConfigParity(options) {
|
|
87
|
+
const out = [];
|
|
88
|
+
checkSgconfig(options, out);
|
|
89
|
+
if (options.localRules.length === 0) {
|
|
90
|
+
out.push({
|
|
91
|
+
name: options.localRuleDir,
|
|
92
|
+
reason: 'empty-local-rules',
|
|
93
|
+
detail: 'no local rule files were provided',
|
|
94
|
+
});
|
|
95
|
+
}
|
|
96
|
+
const packPaths = new Set(options.packRulePaths);
|
|
97
|
+
const packNames = new Set(options.packRulePaths.map((path) => posix.basename(path)));
|
|
98
|
+
const defaultLanguage = options.defaultLanguage ?? 'Tsx';
|
|
99
|
+
const exceptions = options.languageExceptions ?? {};
|
|
100
|
+
for (const rule of options.localRules) {
|
|
101
|
+
if (packPaths.has(rule.path) || packNames.has(posix.basename(rule.path))) {
|
|
102
|
+
out.push({
|
|
103
|
+
name: rule.path,
|
|
104
|
+
reason: 'copied-pack-rule',
|
|
105
|
+
detail: 'matches a rule shipped in the pack; load the pack directory instead of copying',
|
|
106
|
+
});
|
|
107
|
+
}
|
|
108
|
+
if (TSX_COMPANION.test(rule.path)) {
|
|
109
|
+
out.push({
|
|
110
|
+
name: rule.path,
|
|
111
|
+
reason: 'tsx-companion',
|
|
112
|
+
detail: 'remove the -tsx companion rule; the base rule already covers Tsx',
|
|
113
|
+
});
|
|
114
|
+
}
|
|
115
|
+
const expected = Object.hasOwn(exceptions, rule.path)
|
|
116
|
+
? exceptions[rule.path]
|
|
117
|
+
: defaultLanguage;
|
|
118
|
+
checkRuleLanguage(rule, expected, out);
|
|
119
|
+
}
|
|
120
|
+
const known = new Set(options.localRules.map((rule) => rule.path));
|
|
121
|
+
for (const path of Object.keys(exceptions)) {
|
|
122
|
+
if (!known.has(path)) {
|
|
123
|
+
out.push({
|
|
124
|
+
name: path,
|
|
125
|
+
reason: 'rule-language',
|
|
126
|
+
detail: 'language exception names a file that is not a local rule',
|
|
127
|
+
});
|
|
128
|
+
}
|
|
129
|
+
}
|
|
130
|
+
return out;
|
|
131
|
+
}
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
import type { AstGrepConfigParityFile } from './check.mts';
|
|
2
|
+
export type GitLsFilesRunner = (root: string, dir: string) => Promise<string[]>;
|
|
3
|
+
export interface DiscoverAstGrepConfigOptions {
|
|
4
|
+
/** Tracked local rule directory, relative to `root`. */
|
|
5
|
+
localRuleDir: string;
|
|
6
|
+
/** Defaults to `sgconfig.yml`. */
|
|
7
|
+
sgconfigPath?: string;
|
|
8
|
+
/** Installed pack rules directory (absolute, or relative to `root`). Listed from disk. */
|
|
9
|
+
packRulesDir: string;
|
|
10
|
+
/** Allow zero local rule files instead of throwing. Defaults to `false`. */
|
|
11
|
+
allowEmpty?: boolean;
|
|
12
|
+
/** Replaces the `git ls-files` runner; returns root-relative tracked paths under `dir`. */
|
|
13
|
+
listTrackedFiles?: GitLsFilesRunner;
|
|
14
|
+
}
|
|
15
|
+
export interface AstGrepConfigParityInput {
|
|
16
|
+
sgconfig: {
|
|
17
|
+
name: string;
|
|
18
|
+
source: string;
|
|
19
|
+
};
|
|
20
|
+
localRuleDir: string;
|
|
21
|
+
localRules: AstGrepConfigParityFile[];
|
|
22
|
+
packRulePaths: string[];
|
|
23
|
+
}
|
|
24
|
+
/** Runs `git ls-files -z -- <dir>` with an argv array (no shell) from `root`. */
|
|
25
|
+
export declare function gitLsFiles(root: string, dir: string): Promise<string[]>;
|
|
26
|
+
/**
|
|
27
|
+
* Reads `sgconfig.yml`, the git-tracked `*.yml`/`*.yaml` files under `localRuleDir` (recursive) and
|
|
28
|
+
* the installed pack's rule paths, returning the inputs of `checkAstGrepConfigParity`. Throws when
|
|
29
|
+
* local discovery is empty (unless `allowEmpty`) or the pack directory has no rule files.
|
|
30
|
+
*/
|
|
31
|
+
export declare function discoverAstGrepConfig(root: string, options: DiscoverAstGrepConfigOptions): Promise<AstGrepConfigParityInput>;
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
import { execFile } from 'node:child_process';
|
|
2
|
+
import { readdir, readFile } from 'node:fs/promises';
|
|
3
|
+
import { join, posix, resolve } from 'node:path';
|
|
4
|
+
import { promisify } from 'node:util';
|
|
5
|
+
const execFileAsync = promisify(execFile);
|
|
6
|
+
const YAML_FILE = /\.ya?ml$/;
|
|
7
|
+
const byCodeUnit = (a, b) => (a < b ? -1 : 1);
|
|
8
|
+
/** Runs `git ls-files -z -- <dir>` with an argv array (no shell) from `root`. */
|
|
9
|
+
export async function gitLsFiles(root, dir) {
|
|
10
|
+
const { stdout } = await execFileAsync('git', ['ls-files', '-z', '--', dir], {
|
|
11
|
+
cwd: root,
|
|
12
|
+
maxBuffer: 64 * 1024 * 1024,
|
|
13
|
+
});
|
|
14
|
+
return stdout.split('\0').filter(Boolean);
|
|
15
|
+
}
|
|
16
|
+
/**
|
|
17
|
+
* Reads `sgconfig.yml`, the git-tracked `*.yml`/`*.yaml` files under `localRuleDir` (recursive) and
|
|
18
|
+
* the installed pack's rule paths, returning the inputs of `checkAstGrepConfigParity`. Throws when
|
|
19
|
+
* local discovery is empty (unless `allowEmpty`) or the pack directory has no rule files.
|
|
20
|
+
*/
|
|
21
|
+
export async function discoverAstGrepConfig(root, options) {
|
|
22
|
+
const { localRuleDir } = options;
|
|
23
|
+
const dir = posix.normalize(localRuleDir).replace(/\/+$/, '');
|
|
24
|
+
const sgconfigPath = options.sgconfigPath ?? 'sgconfig.yml';
|
|
25
|
+
const tracked = await (options.listTrackedFiles ?? gitLsFiles)(root, dir);
|
|
26
|
+
const prefix = `${dir}/`;
|
|
27
|
+
const paths = tracked
|
|
28
|
+
.filter((path) => path.startsWith(prefix) && YAML_FILE.test(path))
|
|
29
|
+
.map((path) => path.slice(prefix.length))
|
|
30
|
+
.sort(byCodeUnit);
|
|
31
|
+
if (paths.length === 0 && !options.allowEmpty) {
|
|
32
|
+
throw new Error(`No git-tracked ast-grep rule files found under ${join(root, dir)}`);
|
|
33
|
+
}
|
|
34
|
+
const packDir = resolve(root, options.packRulesDir);
|
|
35
|
+
const packRulePaths = (await readdir(packDir, { recursive: true }))
|
|
36
|
+
.map((path) => path.split('\\').join('/'))
|
|
37
|
+
.filter((path) => YAML_FILE.test(path))
|
|
38
|
+
.sort(byCodeUnit);
|
|
39
|
+
if (packRulePaths.length === 0) {
|
|
40
|
+
throw new Error(`No ast-grep pack rule files found under ${packDir}`);
|
|
41
|
+
}
|
|
42
|
+
const [source, localRules] = await Promise.all([
|
|
43
|
+
readFile(join(root, sgconfigPath), 'utf8'),
|
|
44
|
+
Promise.all(paths.map(async (path) => ({
|
|
45
|
+
path,
|
|
46
|
+
source: await readFile(join(root, dir, path), 'utf8'),
|
|
47
|
+
}))),
|
|
48
|
+
]);
|
|
49
|
+
return { sgconfig: { name: sgconfigPath, source }, localRuleDir, localRules, packRulePaths };
|
|
50
|
+
}
|
|
@@ -0,0 +1,2 @@
|
|
|
1
|
+
export { checkAstGrepConfigParity, DEFAULT_LANGUAGE_GLOBS, type AstGrepConfigParityFile, type AstGrepConfigParityOffender, type AstGrepConfigParityReason, type CheckAstGrepConfigParityOptions, } from './check.mts';
|
|
2
|
+
export { discoverAstGrepConfig, gitLsFiles, type AstGrepConfigParityInput, type DiscoverAstGrepConfigOptions, type GitLsFilesRunner, } from './discover.mts';
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
export interface MarkdownArticleInput {
|
|
2
|
+
name: string;
|
|
3
|
+
source: string;
|
|
4
|
+
}
|
|
5
|
+
export interface ParsedMarkdownArticle {
|
|
6
|
+
slug?: string;
|
|
7
|
+
body: string;
|
|
8
|
+
}
|
|
9
|
+
export type MarkdownArticleLinkReason = 'residual-md' | 'missing-target' | 'duplicate-slug';
|
|
10
|
+
export interface MarkdownArticleLinkOffender {
|
|
11
|
+
name: string;
|
|
12
|
+
/** The offending href, or the shared slug for `duplicate-slug`. */
|
|
13
|
+
href: string;
|
|
14
|
+
reason: MarkdownArticleLinkReason;
|
|
15
|
+
}
|
|
16
|
+
export interface CheckMarkdownArticleLinksOptions {
|
|
17
|
+
inputs: readonly MarkdownArticleInput[];
|
|
18
|
+
/** Article route prefix, for example `/article/`. */
|
|
19
|
+
routePrefix: string;
|
|
20
|
+
parse: (source: string) => ParsedMarkdownArticle;
|
|
21
|
+
rewrite: (body: string) => string;
|
|
22
|
+
render: (markdown: string) => string | Promise<string>;
|
|
23
|
+
}
|
|
24
|
+
export declare function articleSlug(name: string, slug: string | undefined): string;
|
|
25
|
+
/**
|
|
26
|
+
* Renders every article and reports local links that still end in `.md`, links to a
|
|
27
|
+
* `<routePrefix><slug>` target no input provides, and slugs shared by more than one input.
|
|
28
|
+
* The caller supplies the parser, link rewriter and renderer; none is bundled here.
|
|
29
|
+
*/
|
|
30
|
+
export declare function checkMarkdownArticleLinks(options: CheckMarkdownArticleLinksOptions): Promise<MarkdownArticleLinkOffender[]>;
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
import { basename } from 'node:path';
|
|
2
|
+
const EXTERNAL_HREF = /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i;
|
|
3
|
+
const HREF_ATTRIBUTE = /(?<=\s)href\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+))/gi;
|
|
4
|
+
const ENTITIES = {
|
|
5
|
+
'"': '"',
|
|
6
|
+
''': "'",
|
|
7
|
+
''': "'",
|
|
8
|
+
'<': '<',
|
|
9
|
+
'>': '>',
|
|
10
|
+
};
|
|
11
|
+
function decodeEntities(value) {
|
|
12
|
+
return value
|
|
13
|
+
.replace(/&(?:quot|#39|#x27|lt|gt);/gi, (e) => ENTITIES[e.toLowerCase()])
|
|
14
|
+
.replace(/&/gi, '&');
|
|
15
|
+
}
|
|
16
|
+
function slugExists(catalog, target) {
|
|
17
|
+
try {
|
|
18
|
+
return catalog.has(decodeURIComponent(target));
|
|
19
|
+
}
|
|
20
|
+
catch {
|
|
21
|
+
return false;
|
|
22
|
+
}
|
|
23
|
+
}
|
|
24
|
+
export function articleSlug(name, slug) {
|
|
25
|
+
return slug || basename(name, '.md');
|
|
26
|
+
}
|
|
27
|
+
function hrefsOf(html) {
|
|
28
|
+
return Array.from(html.matchAll(HREF_ATTRIBUTE), (match) => decodeEntities(match[1] ?? match[2] ?? match[3]));
|
|
29
|
+
}
|
|
30
|
+
function duplicateSlugOffenders(articles) {
|
|
31
|
+
const bySlug = new Map();
|
|
32
|
+
for (const { name, slug } of articles)
|
|
33
|
+
bySlug.set(slug, [...(bySlug.get(slug) ?? []), name]);
|
|
34
|
+
return [...bySlug].flatMap(([slug, names]) => names.length > 1
|
|
35
|
+
? names.map((name) => ({ name, href: slug, reason: 'duplicate-slug' }))
|
|
36
|
+
: []);
|
|
37
|
+
}
|
|
38
|
+
/**
|
|
39
|
+
* Renders every article and reports local links that still end in `.md`, links to a
|
|
40
|
+
* `<routePrefix><slug>` target no input provides, and slugs shared by more than one input.
|
|
41
|
+
* The caller supplies the parser, link rewriter and renderer; none is bundled here.
|
|
42
|
+
*/
|
|
43
|
+
export async function checkMarkdownArticleLinks(options) {
|
|
44
|
+
const articles = options.inputs.map((input) => {
|
|
45
|
+
const parsed = options.parse(input.source);
|
|
46
|
+
return { name: input.name, slug: articleSlug(input.name, parsed.slug), body: parsed.body };
|
|
47
|
+
});
|
|
48
|
+
const catalog = new Set(articles.map((article) => article.slug));
|
|
49
|
+
const offenders = duplicateSlugOffenders(articles);
|
|
50
|
+
for (const { name, body } of articles) {
|
|
51
|
+
const html = await options.render(options.rewrite(body));
|
|
52
|
+
for (const href of hrefsOf(html)) {
|
|
53
|
+
if (EXTERNAL_HREF.test(href))
|
|
54
|
+
continue;
|
|
55
|
+
const path = href.split(/[?#]/)[0];
|
|
56
|
+
if (path.endsWith('.md')) {
|
|
57
|
+
offenders.push({ name, href, reason: 'residual-md' });
|
|
58
|
+
}
|
|
59
|
+
else if (path.startsWith(options.routePrefix)) {
|
|
60
|
+
const target = path.slice(options.routePrefix.length);
|
|
61
|
+
if (!target.includes('/') && !slugExists(catalog, target)) {
|
|
62
|
+
offenders.push({ name, href, reason: 'missing-target' });
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
return offenders;
|
|
68
|
+
}
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
import type { MarkdownArticleInput } from './check.mts';
|
|
2
|
+
export type GitLsFilesRunner = (root: string) => Promise<string[]>;
|
|
3
|
+
export interface DiscoverMarkdownArticlesOptions {
|
|
4
|
+
/** Basenames to skip. Defaults to `['README.md']`. */
|
|
5
|
+
exclude?: readonly string[];
|
|
6
|
+
/** Return an empty list instead of throwing when nothing is found. Defaults to `false`. */
|
|
7
|
+
allowEmpty?: boolean;
|
|
8
|
+
/** Replaces the `git ls-files` runner; receives `root` and returns root-relative tracked paths. */
|
|
9
|
+
listTrackedFiles?: GitLsFilesRunner;
|
|
10
|
+
}
|
|
11
|
+
/** Runs `git ls-files -z -- '*.md'` with an argv array (no shell) from `root`. */
|
|
12
|
+
export declare function gitLsFiles(root: string): Promise<string[]>;
|
|
13
|
+
/**
|
|
14
|
+
* Lists git-tracked `*.md` files directly under `root` (not recursive), minus exclusions,
|
|
15
|
+
* and returns them as sorted `{ name, source }` inputs. Throws when none are found unless
|
|
16
|
+
* `allowEmpty` is set, so a wrong root cannot pass silently.
|
|
17
|
+
*/
|
|
18
|
+
export declare function discoverMarkdownArticles(root: string, options?: DiscoverMarkdownArticlesOptions): Promise<MarkdownArticleInput[]>;
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
import { execFile } from 'node:child_process';
|
|
2
|
+
import { readFile } from 'node:fs/promises';
|
|
3
|
+
import { join } from 'node:path';
|
|
4
|
+
import { promisify } from 'node:util';
|
|
5
|
+
const execFileAsync = promisify(execFile);
|
|
6
|
+
/** Runs `git ls-files -z -- '*.md'` with an argv array (no shell) from `root`. */
|
|
7
|
+
export async function gitLsFiles(root) {
|
|
8
|
+
const { stdout } = await execFileAsync('git', ['ls-files', '-z', '--', '*.md'], {
|
|
9
|
+
cwd: root,
|
|
10
|
+
maxBuffer: 64 * 1024 * 1024,
|
|
11
|
+
});
|
|
12
|
+
return stdout.split('\0').filter(Boolean);
|
|
13
|
+
}
|
|
14
|
+
/**
|
|
15
|
+
* Lists git-tracked `*.md` files directly under `root` (not recursive), minus exclusions,
|
|
16
|
+
* and returns them as sorted `{ name, source }` inputs. Throws when none are found unless
|
|
17
|
+
* `allowEmpty` is set, so a wrong root cannot pass silently.
|
|
18
|
+
*/
|
|
19
|
+
export async function discoverMarkdownArticles(root, options = {}) {
|
|
20
|
+
const exclude = new Set(options.exclude ?? ['README.md']);
|
|
21
|
+
const tracked = await (options.listTrackedFiles ?? gitLsFiles)(root);
|
|
22
|
+
const names = tracked
|
|
23
|
+
.filter((path) => path.endsWith('.md') && !path.includes('/') && !exclude.has(path))
|
|
24
|
+
.sort((a, b) => (a < b ? -1 : 1));
|
|
25
|
+
if (names.length === 0 && !options.allowEmpty) {
|
|
26
|
+
throw new Error(`No git-tracked markdown articles found directly under ${root}`);
|
|
27
|
+
}
|
|
28
|
+
return Promise.all(names.map(async (name) => ({ name, source: await readFile(join(root, name), 'utf8') })));
|
|
29
|
+
}
|
|
@@ -0,0 +1,2 @@
|
|
|
1
|
+
export { articleSlug, checkMarkdownArticleLinks, type CheckMarkdownArticleLinksOptions, type MarkdownArticleInput, type MarkdownArticleLinkOffender, type MarkdownArticleLinkReason, type ParsedMarkdownArticle, } from './check.mts';
|
|
2
|
+
export { discoverMarkdownArticles, gitLsFiles, type DiscoverMarkdownArticlesOptions, type GitLsFilesRunner, } from './discover.mts';
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "vouchington-tooling",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.83.0",
|
|
4
4
|
"description": "Vouchington CLI and extractable tooling libraries.",
|
|
5
5
|
"homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
|
|
6
6
|
"bugs": {
|
|
@@ -231,6 +231,16 @@
|
|
|
231
231
|
"import": "./dist/markdown/index.mjs",
|
|
232
232
|
"default": "./dist/markdown/index.mjs"
|
|
233
233
|
},
|
|
234
|
+
"./ast-grep-config-parity": {
|
|
235
|
+
"types": "./dist/ast-grep-config-parity/index.d.mts",
|
|
236
|
+
"import": "./dist/ast-grep-config-parity/index.mjs",
|
|
237
|
+
"default": "./dist/ast-grep-config-parity/index.mjs"
|
|
238
|
+
},
|
|
239
|
+
"./markdown-article-links": {
|
|
240
|
+
"types": "./dist/markdown-article-links/index.d.mts",
|
|
241
|
+
"import": "./dist/markdown-article-links/index.mjs",
|
|
242
|
+
"default": "./dist/markdown-article-links/index.mjs"
|
|
243
|
+
},
|
|
234
244
|
"./http-body": {
|
|
235
245
|
"types": "./dist/http-body/index.d.mts",
|
|
236
246
|
"import": "./dist/http-body/index.mjs",
|
|
Binary file
|