@shivaedev/quality 0.43.0 → 0.44.1
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/CHANGELOG.md +29 -0
- package/README.md +55 -39
- package/biome/declarations.json +1 -1
- package/biome/preset.json +60 -60
- package/dist/adapters/knip/configuration.d.ts +29 -0
- package/dist/adapters/knip/configuration.d.ts.map +1 -0
- package/dist/adapters/knip/configuration.js +59 -0
- package/dist/adapters/knip/configuration.js.map +1 -0
- package/dist/adapters/knip/entryPointFindings.d.ts +3 -0
- package/dist/adapters/knip/entryPointFindings.d.ts.map +1 -0
- package/dist/adapters/knip/entryPointFindings.js +49 -0
- package/dist/adapters/knip/entryPointFindings.js.map +1 -0
- package/dist/adapters/knip/findings.d.ts +4 -0
- package/dist/adapters/knip/findings.d.ts.map +1 -0
- package/dist/adapters/knip/findings.js +40 -0
- package/dist/adapters/knip/findings.js.map +1 -0
- package/dist/adapters/knip/run.d.ts +3 -0
- package/dist/adapters/knip/run.d.ts.map +1 -0
- package/dist/adapters/knip/run.js +46 -0
- package/dist/adapters/knip/run.js.map +1 -0
- package/dist/adapters/knip/sourceConfig.d.ts +4 -0
- package/dist/adapters/knip/sourceConfig.d.ts.map +1 -0
- package/dist/adapters/knip/sourceConfig.js +15 -0
- package/dist/adapters/knip/sourceConfig.js.map +1 -0
- package/dist/biome/recognizeDiagnostics.js +2 -2
- package/dist/biome/recognizeDiagnostics.js.map +1 -1
- package/dist/docs/documentedImports.d.ts +12 -0
- package/dist/docs/documentedImports.d.ts.map +1 -0
- package/dist/docs/documentedImports.js +80 -0
- package/dist/docs/documentedImports.js.map +1 -0
- package/dist/docs/documentedModule.d.ts +11 -0
- package/dist/docs/documentedModule.d.ts.map +1 -0
- package/dist/docs/documentedModule.js +32 -0
- package/dist/docs/documentedModule.js.map +1 -0
- package/dist/docs/exportsName.d.ts +2 -0
- package/dist/docs/exportsName.d.ts.map +1 -0
- package/dist/docs/exportsName.js +25 -0
- package/dist/docs/exportsName.js.map +1 -0
- package/dist/docs/headingAnchors.d.ts +4 -0
- package/dist/docs/headingAnchors.d.ts.map +1 -0
- package/dist/docs/headingAnchors.js +43 -0
- package/dist/docs/headingAnchors.js.map +1 -0
- package/dist/docs/importFindings.d.ts +12 -0
- package/dist/docs/importFindings.d.ts.map +1 -0
- package/dist/docs/importFindings.js +36 -0
- package/dist/docs/importFindings.js.map +1 -0
- package/dist/docs/isDocument.d.ts +2 -0
- package/dist/docs/isDocument.d.ts.map +1 -0
- package/dist/docs/isDocument.js +6 -0
- package/dist/docs/isDocument.js.map +1 -0
- package/dist/docs/linkFindings.d.ts +12 -0
- package/dist/docs/linkFindings.d.ts.map +1 -0
- package/dist/docs/linkFindings.js +59 -0
- package/dist/docs/linkFindings.js.map +1 -0
- package/dist/docs/markdownLines.d.ts +11 -0
- package/dist/docs/markdownLines.d.ts.map +1 -0
- package/dist/docs/markdownLines.js +38 -0
- package/dist/docs/markdownLines.js.map +1 -0
- package/dist/docs/markdownLinks.d.ts +7 -0
- package/dist/docs/markdownLinks.d.ts.map +1 -0
- package/dist/docs/markdownLinks.js +23 -0
- package/dist/docs/markdownLinks.js.map +1 -0
- package/dist/docs/repositoryLink.d.ts +11 -0
- package/dist/docs/repositoryLink.d.ts.map +1 -0
- package/dist/docs/repositoryLink.js +28 -0
- package/dist/docs/repositoryLink.js.map +1 -0
- package/dist/imports/fences/compilePolicy.d.ts.map +1 -1
- package/dist/imports/fences/compilePolicy.js +1 -1
- package/dist/imports/fences/compilePolicy.js.map +1 -1
- package/dist/imports/fences/match.d.ts +1 -1
- package/dist/imports/fences/match.d.ts.map +1 -1
- package/dist/imports/fences/match.js +1 -1
- package/dist/imports/fences/match.js.map +1 -1
- package/dist/imports/packageExports.d.ts +1 -0
- package/dist/imports/packageExports.d.ts.map +1 -1
- package/dist/imports/packageExports.js +7 -5
- package/dist/imports/packageExports.js.map +1 -1
- package/dist/imports/packageName.d.ts +4 -0
- package/dist/imports/packageName.d.ts.map +1 -0
- package/dist/imports/packageName.js +25 -0
- package/dist/imports/packageName.js.map +1 -0
- package/dist/imports/resolve.d.ts +0 -2
- package/dist/imports/resolve.d.ts.map +1 -1
- package/dist/imports/resolve.js +1 -24
- package/dist/imports/resolve.js.map +1 -1
- package/dist/inventory/collect.d.ts +0 -1
- package/dist/inventory/collect.d.ts.map +1 -1
- package/dist/inventory/collect.js +1 -4
- package/dist/inventory/collect.js.map +1 -1
- package/dist/inventory/linesOf.d.ts +2 -0
- package/dist/inventory/linesOf.d.ts.map +1 -0
- package/dist/inventory/linesOf.js +5 -0
- package/dist/inventory/linesOf.js.map +1 -0
- package/dist/rules/builtIn.d.ts +2 -2
- package/dist/rules/builtIn.d.ts.map +1 -1
- package/dist/rules/builtIn.js +6 -0
- package/dist/rules/builtIn.js.map +1 -1
- package/dist/rules/docs/references.d.ts +2 -0
- package/dist/rules/docs/references.d.ts.map +1 -0
- package/dist/rules/docs/references.js +66 -0
- package/dist/rules/docs/references.js.map +1 -0
- package/dist/rules/docs/unversionedInstalls.d.ts +2 -0
- package/dist/rules/docs/unversionedInstalls.d.ts.map +1 -0
- package/dist/rules/docs/unversionedInstalls.js +36 -0
- package/dist/rules/docs/unversionedInstalls.js.map +1 -0
- package/dist/rules/files/folderNames.js +2 -2
- package/dist/rules/files/folderNames.js.map +1 -1
- package/dist/rules/imports/manifest.js +1 -1
- package/dist/rules/imports/manifest.js.map +1 -1
- package/dist/rules/imports/runtime.js +1 -1
- package/dist/rules/imports/runtime.js.map +1 -1
- package/dist/rules/stories/unitTests.js +1 -1
- package/dist/rules/stories/unitTests.js.map +1 -1
- package/dist/rules/unusedCode.d.ts +2 -0
- package/dist/rules/unusedCode.d.ts.map +1 -0
- package/dist/rules/unusedCode.js +9 -0
- package/dist/rules/unusedCode.js.map +1 -0
- package/docs/debt-and-hooks.md +0 -1
- package/docs/north-star.md +1 -1
- package/package.json +3 -2
- package/src/adapters/knip/configuration.ts +73 -0
- package/src/adapters/knip/entryPointFindings.ts +54 -0
- package/src/adapters/knip/findings.ts +46 -0
- package/src/adapters/knip/run.ts +60 -0
- package/src/adapters/knip/sourceConfig.ts +20 -0
- package/src/biome/recognizeDiagnostics.ts +2 -2
- package/src/docs/documentedImports.ts +104 -0
- package/src/docs/documentedModule.ts +44 -0
- package/src/docs/exportsName.ts +27 -0
- package/src/docs/headingAnchors.ts +52 -0
- package/src/docs/importFindings.ts +62 -0
- package/src/docs/isDocument.ts +6 -0
- package/src/docs/linkFindings.ts +90 -0
- package/src/docs/markdownLines.ts +56 -0
- package/src/docs/markdownLinks.ts +33 -0
- package/src/docs/repositoryLink.ts +44 -0
- package/src/imports/fences/compilePolicy.ts +2 -1
- package/src/imports/fences/match.ts +2 -1
- package/src/imports/packageExports.ts +8 -5
- package/src/imports/packageName.ts +31 -0
- package/src/imports/resolve.ts +1 -31
- package/src/inventory/collect.ts +1 -5
- package/src/inventory/linesOf.ts +4 -0
- package/src/rules/builtIn.ts +6 -0
- package/src/rules/docs/references.ts +83 -0
- package/src/rules/docs/unversionedInstalls.ts +53 -0
- package/src/rules/files/folderNames.ts +2 -2
- package/src/rules/imports/manifest.ts +1 -1
- package/src/rules/imports/runtime.ts +1 -1
- package/src/rules/stories/unitTests.ts +1 -1
- package/src/rules/unusedCode.ts +10 -0
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
export interface Repository {
|
|
2
|
+
readonly name: string;
|
|
3
|
+
readonly owner: string;
|
|
4
|
+
}
|
|
5
|
+
|
|
6
|
+
export interface RepositoryLink {
|
|
7
|
+
readonly anchor: string | undefined;
|
|
8
|
+
readonly path: string;
|
|
9
|
+
}
|
|
10
|
+
|
|
11
|
+
const HOSTED = /github\.com[/:](?<owner>[\w.-]+)\/(?<name>[\w.-]+?)(?:\.git)?\/?$/u;
|
|
12
|
+
|
|
13
|
+
const SHORTHAND = /^(?:github:)?(?<owner>[\w.-]+)\/(?<name>[\w.-]+)$/u;
|
|
14
|
+
|
|
15
|
+
const TREE =
|
|
16
|
+
/^https:\/\/(?:github\.com\/(?<owner>[\w.-]+)\/(?<name>[\w.-]+)\/(?:blob|tree|raw)|raw\.githubusercontent\.com\/(?<rawOwner>[\w.-]+)\/(?<rawName>[\w.-]+))\/(?<ref>[^/]+)\/(?<path>[^?#]*)(?:\?[^#]*)?(?:#(?<anchor>.*))?$/u;
|
|
17
|
+
|
|
18
|
+
const PINNED_REF = /^(?:[\da-f]{7,40}|v?\d+\.\d.*)$|@|%40/iu;
|
|
19
|
+
|
|
20
|
+
function field(value: unknown, key: string): unknown {
|
|
21
|
+
return typeof value === "object" && value !== null && key in value ? Reflect.get(value, key) : undefined;
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
export function repositoryOf(manifest: unknown): Repository | undefined {
|
|
25
|
+
const declared = field(manifest, "repository");
|
|
26
|
+
const url = typeof declared === "string" ? declared : field(declared, "url");
|
|
27
|
+
if (typeof url !== "string") {
|
|
28
|
+
return undefined;
|
|
29
|
+
}
|
|
30
|
+
const groups = (HOSTED.exec(url) ?? SHORTHAND.exec(url))?.groups;
|
|
31
|
+
return groups?.owner === undefined || groups.name === undefined ? undefined : { name: groups.name, owner: groups.owner };
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
// A link pinned to a commit or a release tag shows that snapshot, so only links to a branch describe the current tree.
|
|
35
|
+
export function repositoryLink(url: string, repository: Repository | undefined): RepositoryLink | undefined {
|
|
36
|
+
const groups = TREE.exec(url)?.groups;
|
|
37
|
+
const owner = groups?.owner ?? groups?.rawOwner;
|
|
38
|
+
const name = groups?.name ?? groups?.rawName;
|
|
39
|
+
if (repository === undefined || groups === undefined || owner === undefined || name === undefined) {
|
|
40
|
+
return undefined;
|
|
41
|
+
}
|
|
42
|
+
const same = owner.toLowerCase() === repository.owner.toLowerCase() && name.toLowerCase() === repository.name.toLowerCase();
|
|
43
|
+
return same && !PINNED_REF.test(groups.ref ?? "") ? { anchor: groups.anchor, path: (groups.path ?? "").replace(/\/$/u, "") } : undefined;
|
|
44
|
+
}
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import type { ImportEdge } from "#imports/graph.ts";
|
|
2
|
-
import {
|
|
2
|
+
import { packageNameOf } from "#imports/packageName.ts";
|
|
3
|
+
import type { Endpoint } from "#imports/resolve.ts";
|
|
3
4
|
import { type CompiledFence, compileFence, type FenceGraph } from "./evaluate.ts";
|
|
4
5
|
import type { PolicyScope } from "./match.ts";
|
|
5
6
|
import type { Chain, ExampleStep, Fence } from "./model.ts";
|
|
@@ -1,4 +1,5 @@
|
|
|
1
|
-
import { builtinName,
|
|
1
|
+
import { builtinName, packageNameOf } from "#imports/packageName.ts";
|
|
2
|
+
import type { Endpoint } from "#imports/resolve.ts";
|
|
2
3
|
import { packageOf, type WorkspacePackage } from "#imports/workspace.ts";
|
|
3
4
|
import type { Selector } from "./model.ts";
|
|
4
5
|
|
|
@@ -1,11 +1,11 @@
|
|
|
1
|
-
export function
|
|
1
|
+
export function exportEntry(exports: unknown, subpath: string): readonly [string, unknown] | undefined {
|
|
2
2
|
if (typeof exports !== "object" || exports === null || Array.isArray(exports)) {
|
|
3
|
-
return
|
|
3
|
+
return undefined;
|
|
4
4
|
}
|
|
5
5
|
const entries = Object.entries(exports);
|
|
6
6
|
const exact = entries.find(([key]) => key === subpath);
|
|
7
7
|
if (exact !== undefined) {
|
|
8
|
-
return exact
|
|
8
|
+
return exact;
|
|
9
9
|
}
|
|
10
10
|
const matching = entries.filter(([key]) => {
|
|
11
11
|
const [prefix = "", suffix, ...rest] = key.split("*");
|
|
@@ -17,8 +17,11 @@ export function blockedExport(exports: unknown, subpath: string): boolean {
|
|
|
17
17
|
&& subpath.endsWith(suffix)
|
|
18
18
|
);
|
|
19
19
|
});
|
|
20
|
-
|
|
21
|
-
|
|
20
|
+
return matching.toSorted(([left], [right]) => right.indexOf("*") - left.indexOf("*") || right.length - left.length)[0];
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
export function blockedExport(exports: unknown, subpath: string): boolean {
|
|
24
|
+
return exportEntry(exports, subpath)?.[1] === null;
|
|
22
25
|
}
|
|
23
26
|
|
|
24
27
|
export function exportTargets(value: unknown): string[] {
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
import { isBuiltin } from "node:module";
|
|
2
|
+
|
|
3
|
+
const NODE_PREFIX = "node:";
|
|
4
|
+
|
|
5
|
+
const TYPES_SCOPE = "@types";
|
|
6
|
+
|
|
7
|
+
const TYPES_SCOPE_SEPARATOR = "__";
|
|
8
|
+
|
|
9
|
+
export function builtinName(specifier: string): string | undefined {
|
|
10
|
+
if (!isBuiltin(specifier)) {
|
|
11
|
+
return undefined;
|
|
12
|
+
}
|
|
13
|
+
return specifier.startsWith(NODE_PREFIX) ? specifier : `${NODE_PREFIX}${specifier}`;
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
function typedName(name: string): string {
|
|
17
|
+
return name.includes(TYPES_SCOPE_SEPARATOR) ? `@${name.replace(TYPES_SCOPE_SEPARATOR, "/")}` : name;
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
export function nameAt(path: string): string {
|
|
21
|
+
const [first = "", second] = path.split("/");
|
|
22
|
+
if (second === undefined || !first.startsWith("@")) {
|
|
23
|
+
return first;
|
|
24
|
+
}
|
|
25
|
+
return first === TYPES_SCOPE ? typedName(second) : `${first}/${second}`;
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
// The example checker and the graph name a package through this one function, so a fence example and a real import cannot disagree.
|
|
29
|
+
export function packageNameOf(specifier: string): string {
|
|
30
|
+
return builtinName(specifier) ?? nameAt(specifier);
|
|
31
|
+
}
|
package/src/imports/resolve.ts
CHANGED
|
@@ -1,18 +1,16 @@
|
|
|
1
1
|
import { realpathSync } from "node:fs";
|
|
2
|
-
import { isBuiltin } from "node:module";
|
|
3
2
|
import { dirname, join, relative } from "node:path";
|
|
4
3
|
import ts from "typescript";
|
|
5
4
|
import { posix } from "#inventory/ignoreScope.ts";
|
|
6
5
|
import type { Ambient } from "./ambient.ts";
|
|
7
6
|
import type { ImportRequest } from "./extract.ts";
|
|
7
|
+
import { builtinName, nameAt, packageNameOf } from "./packageName.ts";
|
|
8
8
|
import type { Project } from "./projects.ts";
|
|
9
9
|
|
|
10
10
|
export type Endpoint =
|
|
11
11
|
| { readonly kind: "file"; readonly path: string }
|
|
12
12
|
| { readonly kind: "external"; readonly package: string; readonly specifier: string };
|
|
13
13
|
|
|
14
|
-
const NODE_PREFIX = "node:";
|
|
15
|
-
|
|
16
14
|
const NODE_MODULES = "/node_modules/";
|
|
17
15
|
|
|
18
16
|
const ASSET_DECLARATION = /\.d(?<extension>\.[^./]+)\.ts$/u;
|
|
@@ -31,34 +29,6 @@ const presumingHost: ts.ModuleResolutionHost = {
|
|
|
31
29
|
fileExists: (path) => !path.endsWith(`/${PACKAGE_JSON}`) || ts.sys.fileExists(path),
|
|
32
30
|
};
|
|
33
31
|
|
|
34
|
-
export function builtinName(specifier: string): string | undefined {
|
|
35
|
-
if (!isBuiltin(specifier)) {
|
|
36
|
-
return undefined;
|
|
37
|
-
}
|
|
38
|
-
return specifier.startsWith(NODE_PREFIX) ? specifier : `${NODE_PREFIX}${specifier}`;
|
|
39
|
-
}
|
|
40
|
-
|
|
41
|
-
const TYPES_SCOPE = "@types";
|
|
42
|
-
|
|
43
|
-
const TYPES_SCOPE_SEPARATOR = "__";
|
|
44
|
-
|
|
45
|
-
function typedName(name: string): string {
|
|
46
|
-
return name.includes(TYPES_SCOPE_SEPARATOR) ? `@${name.replace(TYPES_SCOPE_SEPARATOR, "/")}` : name;
|
|
47
|
-
}
|
|
48
|
-
|
|
49
|
-
function nameAt(path: string): string {
|
|
50
|
-
const [first = "", second] = path.split("/");
|
|
51
|
-
if (second === undefined || !first.startsWith("@")) {
|
|
52
|
-
return first;
|
|
53
|
-
}
|
|
54
|
-
return first === TYPES_SCOPE ? typedName(second) : `${first}/${second}`;
|
|
55
|
-
}
|
|
56
|
-
|
|
57
|
-
// The example checker and the graph name a package through this one function, so a fence example and a real import cannot disagree.
|
|
58
|
-
export function packageNameOf(specifier: string): string {
|
|
59
|
-
return builtinName(specifier) ?? nameAt(specifier);
|
|
60
|
-
}
|
|
61
|
-
|
|
62
32
|
function assetOf(declaration: string): string {
|
|
63
33
|
return declaration.replace(ASSET_DECLARATION, "$<extension>");
|
|
64
34
|
}
|
package/src/inventory/collect.ts
CHANGED
|
@@ -4,6 +4,7 @@ import ignore from "ignore";
|
|
|
4
4
|
import type { SourceFile } from "#rule.ts";
|
|
5
5
|
import { FilesystemFailure, orWhenAbsent, readRequiredText } from "./filesystem.ts";
|
|
6
6
|
import { posix } from "./ignoreScope.ts";
|
|
7
|
+
import { linesOf } from "./linesOf.ts";
|
|
7
8
|
import { shadcnFolders } from "./shadcnFolders.ts";
|
|
8
9
|
import { scopeAbove, walk } from "./walk.ts";
|
|
9
10
|
|
|
@@ -20,11 +21,6 @@ export interface Inventory {
|
|
|
20
21
|
|
|
21
22
|
const READ_CONCURRENCY = 16;
|
|
22
23
|
|
|
23
|
-
export function linesOf(text: string): readonly string[] {
|
|
24
|
-
const lines = text.split("\n");
|
|
25
|
-
return lines.at(-1) === "" ? lines.slice(0, -1) : lines;
|
|
26
|
-
}
|
|
27
|
-
|
|
28
24
|
const zoneFiles = Effect.fn("Inventory.zoneFiles")(function* (
|
|
29
25
|
root: string,
|
|
30
26
|
zone: string,
|
package/src/rules/builtIn.ts
CHANGED
|
@@ -5,6 +5,8 @@ import { noJsdoc } from "#rules/comments/noJsdoc.ts";
|
|
|
5
5
|
import { noLineReference } from "#rules/comments/noLineReference.ts";
|
|
6
6
|
import { noPrReference } from "#rules/comments/noPrReference.ts";
|
|
7
7
|
import { noTodo } from "#rules/comments/noTodo.ts";
|
|
8
|
+
import { docsReferences } from "#rules/docs/references.ts";
|
|
9
|
+
import { docsUnversionedInstalls } from "#rules/docs/unversionedInstalls.ts";
|
|
8
10
|
import { effectBoundary } from "#rules/effect/boundary.ts";
|
|
9
11
|
import { serviceParameters } from "#rules/effect/serviceParameters.ts";
|
|
10
12
|
import { distinctCase } from "#rules/files/distinctCase.ts";
|
|
@@ -44,8 +46,10 @@ import { manifestsSourceFirst } from "./manifestsSourceFirst.ts";
|
|
|
44
46
|
import { maxDepth } from "./maxDepth.ts";
|
|
45
47
|
import { maxLines } from "./maxLines.ts";
|
|
46
48
|
import { noBarrel } from "./noBarrel.ts";
|
|
49
|
+
import { unusedCode } from "./unusedCode.ts";
|
|
47
50
|
|
|
48
51
|
export const builtInRules = [
|
|
52
|
+
unusedCode,
|
|
49
53
|
effectBoundary,
|
|
50
54
|
serviceParameters,
|
|
51
55
|
jsxConditionals,
|
|
@@ -59,6 +63,8 @@ export const builtInRules = [
|
|
|
59
63
|
noTodo,
|
|
60
64
|
noEnvironmentPragma,
|
|
61
65
|
maxPerFile,
|
|
66
|
+
docsReferences,
|
|
67
|
+
docsUnversionedInstalls,
|
|
62
68
|
noInline,
|
|
63
69
|
noDoubleCast,
|
|
64
70
|
noIgnoreDeprecations,
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
import { join, posix } from "node:path";
|
|
2
|
+
import { Effect, Option, Schema } from "effect";
|
|
3
|
+
import ts from "typescript";
|
|
4
|
+
import { headingAnchors } from "#docs/headingAnchors.ts";
|
|
5
|
+
import { importFindings } from "#docs/importFindings.ts";
|
|
6
|
+
import { isDocument } from "#docs/isDocument.ts";
|
|
7
|
+
import { linkFindings } from "#docs/linkFindings.ts";
|
|
8
|
+
import { markdownLines } from "#docs/markdownLines.ts";
|
|
9
|
+
import { repositoryOf } from "#docs/repositoryLink.ts";
|
|
10
|
+
import { type WorkspacePackage, workspacePackages } from "#imports/workspace.ts";
|
|
11
|
+
import { defineRule, type Finding, type RuleInputs } from "#rule.ts";
|
|
12
|
+
|
|
13
|
+
const decodeJson = Schema.decodeUnknownOption(Schema.fromJsonString(Schema.Unknown));
|
|
14
|
+
|
|
15
|
+
function field(value: unknown, key: string): unknown {
|
|
16
|
+
return typeof value === "object" && value !== null && key in value ? Reflect.get(value, key) : undefined;
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
// A linked document, such as CLAUDE.md beside AGENTS.md, is checked once through its target.
|
|
20
|
+
function isLink(root: string, file: string): boolean {
|
|
21
|
+
const real = ts.sys.realpath ?? ((path: string) => path);
|
|
22
|
+
return real(join(root, file)) !== join(real(root), file);
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
function reader(inputs: RuleInputs): (path: string) => Effect.Effect<string | undefined> {
|
|
26
|
+
return (path) => Effect.promise(() => inputs.readText(path));
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
function jsonAt(read: ReturnType<typeof reader>, path: string): Effect.Effect<unknown> {
|
|
30
|
+
return Effect.map(read(path), (text) => (text === undefined ? undefined : Option.getOrUndefined(decodeJson(text))));
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
function anchorsReader(read: ReturnType<typeof reader>): (path: string) => Effect.Effect<ReadonlySet<string> | undefined> {
|
|
34
|
+
const known = new Map<string, ReadonlySet<string> | undefined>();
|
|
35
|
+
return (path) =>
|
|
36
|
+
known.has(path)
|
|
37
|
+
? Effect.succeed(known.get(path))
|
|
38
|
+
: Effect.map(read(path), (text) => {
|
|
39
|
+
const anchors = text === undefined ? undefined : headingAnchors(markdownLines(text));
|
|
40
|
+
known.set(path, anchors);
|
|
41
|
+
return anchors;
|
|
42
|
+
});
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
const references = Effect.fn("Docs.references")(function* (inputs: RuleInputs) {
|
|
46
|
+
const read = reader(inputs);
|
|
47
|
+
const packages: readonly WorkspacePackage[] = yield* Effect.promise(() => workspacePackages(inputs));
|
|
48
|
+
const manifests = new Map(
|
|
49
|
+
yield* Effect.forEach(packages, (owner) =>
|
|
50
|
+
Effect.map(jsonAt(read, posix.join(owner.directory, "package.json")), (manifest) => [owner.name, manifest] as const),
|
|
51
|
+
),
|
|
52
|
+
);
|
|
53
|
+
const shared = {
|
|
54
|
+
anchors: anchorsReader(read),
|
|
55
|
+
exports: new Map([...manifests].map(([name, manifest]) => [name, field(manifest, "exports")])),
|
|
56
|
+
packages: new Map(packages.map((owner) => [owner.name, owner])),
|
|
57
|
+
readText: read,
|
|
58
|
+
repository: repositoryOf(yield* jsonAt(read, "package.json")),
|
|
59
|
+
root: inputs.root,
|
|
60
|
+
};
|
|
61
|
+
const documents = inputs.files.filter((file) => isDocument(file) && !isLink(inputs.root, file));
|
|
62
|
+
const findings = yield* Effect.forEach(documents, (file) =>
|
|
63
|
+
Effect.flatMap(read(file), (text): Effect.Effect<readonly Finding[]> => {
|
|
64
|
+
if (text === undefined) {
|
|
65
|
+
return Effect.succeed([]);
|
|
66
|
+
}
|
|
67
|
+
const readme = packages.find((owner) => file === posix.join(owner.directory, "README.md"));
|
|
68
|
+
const published = readme !== undefined && field(manifests.get(readme.name), "private") !== true ? readme.directory : undefined;
|
|
69
|
+
const context = { ...shared, owner: readme?.name, published };
|
|
70
|
+
return Effect.map(Effect.all([linkFindings(context, file, markdownLines(text)), importFindings(context, file, text)]), (found) =>
|
|
71
|
+
found.flat().toSorted((left, right) => (left.line ?? 0) - (right.line ?? 0)),
|
|
72
|
+
);
|
|
73
|
+
}),
|
|
74
|
+
);
|
|
75
|
+
return findings.flat();
|
|
76
|
+
});
|
|
77
|
+
|
|
78
|
+
export const docsReferences = defineRule({
|
|
79
|
+
check: (inputs) => Effect.runPromise(references(inputs)),
|
|
80
|
+
description:
|
|
81
|
+
"Links, heading anchors and documented modules and exports in Markdown resolve, so documentation cannot point at a file, a heading or an API that no longer exists.",
|
|
82
|
+
id: "docs/references",
|
|
83
|
+
});
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
import { Effect } from "effect";
|
|
2
|
+
import { isDocument } from "#docs/isDocument.ts";
|
|
3
|
+
import { codeSpans, type MarkdownLine, markdownLines } from "#docs/markdownLines.ts";
|
|
4
|
+
import { defineRule, type Finding, type RuleInputs } from "#rule.ts";
|
|
5
|
+
|
|
6
|
+
const SHELL_LANGUAGES: ReadonlySet<string> = new Set(["", "bash", "console", "sh", "shell", "zsh"]);
|
|
7
|
+
|
|
8
|
+
const INSTALL = /\b(?:(?:pnpm|npm|yarn|bun)\s+(?:add|install|i|dlx|exec|create|x)|npx|bunx)\s+(?<rest>[^;&|]+)/gu;
|
|
9
|
+
|
|
10
|
+
const VERSIONED = /^(?<name>@?[^@\s]+)@(?<version>[\d*<=>^~].*)$/u;
|
|
11
|
+
|
|
12
|
+
function commandsIn(line: MarkdownLine): readonly string[] {
|
|
13
|
+
if (line.kind === "code") {
|
|
14
|
+
return SHELL_LANGUAGES.has(line.language) ? [line.text] : [];
|
|
15
|
+
}
|
|
16
|
+
return line.kind === "prose" ? codeSpans(line.text) : [];
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
function versioned(command: string): readonly string[] {
|
|
20
|
+
return [...command.matchAll(INSTALL)].flatMap((match) =>
|
|
21
|
+
(match.groups?.rest ?? "").split(/\s+/u).filter((token) => !token.startsWith("-") && VERSIONED.test(token)),
|
|
22
|
+
);
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
function findingsIn(file: string, text: string): readonly Finding[] {
|
|
26
|
+
return markdownLines(text).flatMap((line) =>
|
|
27
|
+
commandsIn(line)
|
|
28
|
+
.flatMap(versioned)
|
|
29
|
+
.map((token) => ({
|
|
30
|
+
file,
|
|
31
|
+
line: line.number,
|
|
32
|
+
message: `"${token}" pins a version in an install command. Name the package alone, ${VERSIONED.exec(token)?.groups?.name}: its manifest's version ranges decide what installs, and a version written in documentation goes stale with the next release.`,
|
|
33
|
+
subject: token,
|
|
34
|
+
})),
|
|
35
|
+
);
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
const unversionedInstalls = Effect.fn("Docs.unversionedInstalls")(function* (inputs: RuleInputs) {
|
|
39
|
+
const findings = yield* Effect.forEach(inputs.files.filter(isDocument), (file) =>
|
|
40
|
+
Effect.map(
|
|
41
|
+
Effect.promise(() => inputs.readText(file)),
|
|
42
|
+
(text) => (text === undefined ? [] : findingsIn(file, text)),
|
|
43
|
+
),
|
|
44
|
+
);
|
|
45
|
+
return findings.flat();
|
|
46
|
+
});
|
|
47
|
+
|
|
48
|
+
export const docsUnversionedInstalls = defineRule({
|
|
49
|
+
check: (inputs) => Effect.runPromise(unversionedInstalls(inputs)),
|
|
50
|
+
description:
|
|
51
|
+
"Install commands in Markdown name packages without versions, so documentation never tells a reader to install a release it has already left behind.",
|
|
52
|
+
id: "docs/unversioned-installs",
|
|
53
|
+
});
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { posix } from "node:path";
|
|
2
|
-
import { Effect, Schema } from "effect";
|
|
2
|
+
import { Effect, Order, Schema } from "effect";
|
|
3
3
|
import ignore, { type Ignore } from "ignore";
|
|
4
4
|
import { nativeNames } from "#naming/nativeNames.ts";
|
|
5
5
|
import { packageLayout } from "#naming/packageLayout.ts";
|
|
@@ -22,7 +22,7 @@ function foldersIn(files: readonly string[]): readonly string[] {
|
|
|
22
22
|
folders.add(folder);
|
|
23
23
|
}
|
|
24
24
|
}
|
|
25
|
-
return [...folders].sort();
|
|
25
|
+
return [...folders].sort(Order.String);
|
|
26
26
|
}
|
|
27
27
|
|
|
28
28
|
function stemsIn(files: readonly string[]): ReadonlySet<string> {
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { posix } from "node:path";
|
|
2
2
|
import { type ImportGraph, importGraph } from "#imports/graph.ts";
|
|
3
3
|
import { isTooling } from "#imports/isTooling.ts";
|
|
4
|
-
import { builtinName } from "#imports/
|
|
4
|
+
import { builtinName } from "#imports/packageName.ts";
|
|
5
5
|
import { packageOf, type WorkspacePackage } from "#imports/workspace.ts";
|
|
6
6
|
import { type EntryPoint, entryPointsOf, isApplication, provider, SHIPPED_FIELDS } from "#manifests/entryPoints.ts";
|
|
7
7
|
import { isTestCode } from "#naming/testName.ts";
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { importGraph } from "#imports/graph.ts";
|
|
2
|
-
import { builtinName } from "#imports/
|
|
2
|
+
import { builtinName } from "#imports/packageName.ts";
|
|
3
3
|
import { type Runtime, runtimeDeclarationProblems, runtimeOf } from "#imports/runtime.ts";
|
|
4
4
|
import { isTestCode } from "#naming/testName.ts";
|
|
5
5
|
import { defineRule } from "#rule.ts";
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { labelOf, outgoing, type Reached, type Trail, walkFrom } from "#imports/fences/reach.ts";
|
|
2
2
|
import type { ImportEdge, ImportGraph } from "#imports/graph.ts";
|
|
3
|
-
import { packageNameOf } from "#imports/
|
|
3
|
+
import { packageNameOf } from "#imports/packageName.ts";
|
|
4
4
|
import { isTestSupport } from "#naming/testName.ts";
|
|
5
5
|
import type { Finding, SourceFile } from "#rule.ts";
|
|
6
6
|
import { parse } from "#rules/parse.ts";
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
import { runKnip } from "#adapters/knip/run.ts";
|
|
2
|
+
import { defineRule } from "#rule.ts";
|
|
3
|
+
|
|
4
|
+
export const unusedCode = defineRule({
|
|
5
|
+
check: runKnip,
|
|
6
|
+
description:
|
|
7
|
+
"Reports unused files, exports and package dependencies, and missing dependencies, through knip. Reach code from declared entry points or remove it; record existing debt in the baseline.",
|
|
8
|
+
id: "code/unused",
|
|
9
|
+
registrable: false,
|
|
10
|
+
});
|