@shivaedev/quality 0.42.0 → 0.44.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.
Files changed (214) hide show
  1. package/CHANGELOG.md +51 -0
  2. package/README.md +98 -38
  3. package/biome/declarations.json +6 -1
  4. package/biome/plugins/ambient-runtime.grit +3 -1
  5. package/biome/preset.json +62 -62
  6. package/dist/adapters/knip/configuration.d.ts +29 -0
  7. package/dist/adapters/knip/configuration.d.ts.map +1 -0
  8. package/dist/adapters/knip/configuration.js +56 -0
  9. package/dist/adapters/knip/configuration.js.map +1 -0
  10. package/dist/adapters/knip/entryPointFindings.d.ts +3 -0
  11. package/dist/adapters/knip/entryPointFindings.d.ts.map +1 -0
  12. package/dist/adapters/knip/entryPointFindings.js +49 -0
  13. package/dist/adapters/knip/entryPointFindings.js.map +1 -0
  14. package/dist/adapters/knip/findings.d.ts +4 -0
  15. package/dist/adapters/knip/findings.d.ts.map +1 -0
  16. package/dist/adapters/knip/findings.js +40 -0
  17. package/dist/adapters/knip/findings.js.map +1 -0
  18. package/dist/adapters/knip/run.d.ts +3 -0
  19. package/dist/adapters/knip/run.d.ts.map +1 -0
  20. package/dist/adapters/knip/run.js +46 -0
  21. package/dist/adapters/knip/run.js.map +1 -0
  22. package/dist/adapters/knip/sourceConfig.d.ts +4 -0
  23. package/dist/adapters/knip/sourceConfig.d.ts.map +1 -0
  24. package/dist/adapters/knip/sourceConfig.js +15 -0
  25. package/dist/adapters/knip/sourceConfig.js.map +1 -0
  26. package/dist/biome/recognizeDiagnostics.js +2 -2
  27. package/dist/biome/recognizeDiagnostics.js.map +1 -1
  28. package/dist/docs/documentedImports.d.ts +12 -0
  29. package/dist/docs/documentedImports.d.ts.map +1 -0
  30. package/dist/docs/documentedImports.js +80 -0
  31. package/dist/docs/documentedImports.js.map +1 -0
  32. package/dist/docs/documentedModule.d.ts +11 -0
  33. package/dist/docs/documentedModule.d.ts.map +1 -0
  34. package/dist/docs/documentedModule.js +32 -0
  35. package/dist/docs/documentedModule.js.map +1 -0
  36. package/dist/docs/exportsName.d.ts +2 -0
  37. package/dist/docs/exportsName.d.ts.map +1 -0
  38. package/dist/docs/exportsName.js +25 -0
  39. package/dist/docs/exportsName.js.map +1 -0
  40. package/dist/docs/headingAnchors.d.ts +4 -0
  41. package/dist/docs/headingAnchors.d.ts.map +1 -0
  42. package/dist/docs/headingAnchors.js +43 -0
  43. package/dist/docs/headingAnchors.js.map +1 -0
  44. package/dist/docs/importFindings.d.ts +12 -0
  45. package/dist/docs/importFindings.d.ts.map +1 -0
  46. package/dist/docs/importFindings.js +36 -0
  47. package/dist/docs/importFindings.js.map +1 -0
  48. package/dist/docs/isDocument.d.ts +2 -0
  49. package/dist/docs/isDocument.d.ts.map +1 -0
  50. package/dist/docs/isDocument.js +6 -0
  51. package/dist/docs/isDocument.js.map +1 -0
  52. package/dist/docs/linkFindings.d.ts +12 -0
  53. package/dist/docs/linkFindings.d.ts.map +1 -0
  54. package/dist/docs/linkFindings.js +59 -0
  55. package/dist/docs/linkFindings.js.map +1 -0
  56. package/dist/docs/markdownLines.d.ts +11 -0
  57. package/dist/docs/markdownLines.d.ts.map +1 -0
  58. package/dist/docs/markdownLines.js +38 -0
  59. package/dist/docs/markdownLines.js.map +1 -0
  60. package/dist/docs/markdownLinks.d.ts +7 -0
  61. package/dist/docs/markdownLinks.d.ts.map +1 -0
  62. package/dist/docs/markdownLinks.js +23 -0
  63. package/dist/docs/markdownLinks.js.map +1 -0
  64. package/dist/docs/repositoryLink.d.ts +11 -0
  65. package/dist/docs/repositoryLink.d.ts.map +1 -0
  66. package/dist/docs/repositoryLink.js +28 -0
  67. package/dist/docs/repositoryLink.js.map +1 -0
  68. package/dist/imports/fences/compilePolicy.d.ts.map +1 -1
  69. package/dist/imports/fences/compilePolicy.js +1 -1
  70. package/dist/imports/fences/compilePolicy.js.map +1 -1
  71. package/dist/imports/fences/match.d.ts +1 -1
  72. package/dist/imports/fences/match.d.ts.map +1 -1
  73. package/dist/imports/fences/match.js +1 -1
  74. package/dist/imports/fences/match.js.map +1 -1
  75. package/dist/imports/packageExports.d.ts +1 -0
  76. package/dist/imports/packageExports.d.ts.map +1 -1
  77. package/dist/imports/packageExports.js +7 -5
  78. package/dist/imports/packageExports.js.map +1 -1
  79. package/dist/imports/packageName.d.ts +4 -0
  80. package/dist/imports/packageName.d.ts.map +1 -0
  81. package/dist/imports/packageName.js +25 -0
  82. package/dist/imports/packageName.js.map +1 -0
  83. package/dist/imports/resolve.d.ts +0 -2
  84. package/dist/imports/resolve.d.ts.map +1 -1
  85. package/dist/imports/resolve.js +1 -24
  86. package/dist/imports/resolve.js.map +1 -1
  87. package/dist/inventory/collect.d.ts +0 -1
  88. package/dist/inventory/collect.d.ts.map +1 -1
  89. package/dist/inventory/collect.js +1 -4
  90. package/dist/inventory/collect.js.map +1 -1
  91. package/dist/inventory/linesOf.d.ts +2 -0
  92. package/dist/inventory/linesOf.d.ts.map +1 -0
  93. package/dist/inventory/linesOf.js +5 -0
  94. package/dist/inventory/linesOf.js.map +1 -0
  95. package/dist/rules/builtIn.d.ts +2 -2
  96. package/dist/rules/builtIn.d.ts.map +1 -1
  97. package/dist/rules/builtIn.js +12 -0
  98. package/dist/rules/builtIn.js.map +1 -1
  99. package/dist/rules/docs/references.d.ts +2 -0
  100. package/dist/rules/docs/references.d.ts.map +1 -0
  101. package/dist/rules/docs/references.js +66 -0
  102. package/dist/rules/docs/references.js.map +1 -0
  103. package/dist/rules/docs/unversionedInstalls.d.ts +2 -0
  104. package/dist/rules/docs/unversionedInstalls.d.ts.map +1 -0
  105. package/dist/rules/docs/unversionedInstalls.js +36 -0
  106. package/dist/rules/docs/unversionedInstalls.js.map +1 -0
  107. package/dist/rules/effect/boundary.d.ts +2 -0
  108. package/dist/rules/effect/boundary.d.ts.map +1 -0
  109. package/dist/rules/effect/boundary.js +66 -0
  110. package/dist/rules/effect/boundary.js.map +1 -0
  111. package/dist/rules/effect/layerConstructor.d.ts +3 -0
  112. package/dist/rules/effect/layerConstructor.d.ts.map +1 -0
  113. package/dist/rules/effect/layerConstructor.js +35 -0
  114. package/dist/rules/effect/layerConstructor.js.map +1 -0
  115. package/dist/rules/effect/ownsParameters.d.ts +3 -0
  116. package/dist/rules/effect/ownsParameters.d.ts.map +1 -0
  117. package/dist/rules/effect/ownsParameters.js +45 -0
  118. package/dist/rules/effect/ownsParameters.js.map +1 -0
  119. package/dist/rules/effect/program.d.ts +4 -0
  120. package/dist/rules/effect/program.d.ts.map +1 -0
  121. package/dist/rules/effect/program.js +24 -0
  122. package/dist/rules/effect/program.js.map +1 -0
  123. package/dist/rules/effect/publicFunctions.d.ts +3 -0
  124. package/dist/rules/effect/publicFunctions.d.ts.map +1 -0
  125. package/dist/rules/effect/publicFunctions.js +68 -0
  126. package/dist/rules/effect/publicFunctions.js.map +1 -0
  127. package/dist/rules/effect/serviceCatalog.d.ts +8 -0
  128. package/dist/rules/effect/serviceCatalog.d.ts.map +1 -0
  129. package/dist/rules/effect/serviceCatalog.js +56 -0
  130. package/dist/rules/effect/serviceCatalog.js.map +1 -0
  131. package/dist/rules/effect/serviceFindings.d.ts +5 -0
  132. package/dist/rules/effect/serviceFindings.d.ts.map +1 -0
  133. package/dist/rules/effect/serviceFindings.js +88 -0
  134. package/dist/rules/effect/serviceFindings.js.map +1 -0
  135. package/dist/rules/effect/serviceOrigin.d.ts +3 -0
  136. package/dist/rules/effect/serviceOrigin.d.ts.map +1 -0
  137. package/dist/rules/effect/serviceOrigin.js +85 -0
  138. package/dist/rules/effect/serviceOrigin.js.map +1 -0
  139. package/dist/rules/effect/serviceParameters.d.ts +2 -0
  140. package/dist/rules/effect/serviceParameters.d.ts.map +1 -0
  141. package/dist/rules/effect/serviceParameters.js +33 -0
  142. package/dist/rules/effect/serviceParameters.js.map +1 -0
  143. package/dist/rules/effect/serviceTypes.d.ts +8 -0
  144. package/dist/rules/effect/serviceTypes.d.ts.map +1 -0
  145. package/dist/rules/effect/serviceTypes.js +94 -0
  146. package/dist/rules/effect/serviceTypes.js.map +1 -0
  147. package/dist/rules/files/folderNames.js +2 -2
  148. package/dist/rules/files/folderNames.js.map +1 -1
  149. package/dist/rules/imports/manifest.js +1 -1
  150. package/dist/rules/imports/manifest.js.map +1 -1
  151. package/dist/rules/imports/runtime.js +1 -1
  152. package/dist/rules/imports/runtime.js.map +1 -1
  153. package/dist/rules/react/jsxConditionals.d.ts +2 -0
  154. package/dist/rules/react/jsxConditionals.d.ts.map +1 -0
  155. package/dist/rules/react/jsxConditionals.js +54 -0
  156. package/dist/rules/react/jsxConditionals.js.map +1 -0
  157. package/dist/rules/stories/engineOf.d.ts.map +1 -1
  158. package/dist/rules/stories/engineOf.js +2 -1
  159. package/dist/rules/stories/engineOf.js.map +1 -1
  160. package/dist/rules/stories/namedValues.js +4 -4
  161. package/dist/rules/stories/namedValues.js.map +1 -1
  162. package/dist/rules/stories/unitTests.js +1 -1
  163. package/dist/rules/stories/unitTests.js.map +1 -1
  164. package/dist/rules/unusedCode.d.ts +2 -0
  165. package/dist/rules/unusedCode.d.ts.map +1 -0
  166. package/dist/rules/unusedCode.js +9 -0
  167. package/dist/rules/unusedCode.js.map +1 -0
  168. package/docs/debt-and-hooks.md +0 -1
  169. package/docs/north-star.md +1 -1
  170. package/package.json +5 -4
  171. package/src/adapters/knip/configuration.ts +66 -0
  172. package/src/adapters/knip/entryPointFindings.ts +54 -0
  173. package/src/adapters/knip/findings.ts +46 -0
  174. package/src/adapters/knip/run.ts +60 -0
  175. package/src/adapters/knip/sourceConfig.ts +20 -0
  176. package/src/biome/recognizeDiagnostics.ts +2 -2
  177. package/src/docs/documentedImports.ts +104 -0
  178. package/src/docs/documentedModule.ts +44 -0
  179. package/src/docs/exportsName.ts +27 -0
  180. package/src/docs/headingAnchors.ts +52 -0
  181. package/src/docs/importFindings.ts +62 -0
  182. package/src/docs/isDocument.ts +6 -0
  183. package/src/docs/linkFindings.ts +90 -0
  184. package/src/docs/markdownLines.ts +56 -0
  185. package/src/docs/markdownLinks.ts +33 -0
  186. package/src/docs/repositoryLink.ts +44 -0
  187. package/src/imports/fences/compilePolicy.ts +2 -1
  188. package/src/imports/fences/match.ts +2 -1
  189. package/src/imports/packageExports.ts +8 -5
  190. package/src/imports/packageName.ts +31 -0
  191. package/src/imports/resolve.ts +1 -31
  192. package/src/inventory/collect.ts +1 -5
  193. package/src/inventory/linesOf.ts +4 -0
  194. package/src/rules/builtIn.ts +12 -0
  195. package/src/rules/docs/references.ts +83 -0
  196. package/src/rules/docs/unversionedInstalls.ts +53 -0
  197. package/src/rules/effect/boundary.ts +75 -0
  198. package/src/rules/effect/layerConstructor.ts +40 -0
  199. package/src/rules/effect/ownsParameters.ts +46 -0
  200. package/src/rules/effect/program.ts +26 -0
  201. package/src/rules/effect/publicFunctions.ts +70 -0
  202. package/src/rules/effect/serviceCatalog.ts +57 -0
  203. package/src/rules/effect/serviceFindings.ts +96 -0
  204. package/src/rules/effect/serviceOrigin.ts +94 -0
  205. package/src/rules/effect/serviceParameters.ts +35 -0
  206. package/src/rules/effect/serviceTypes.ts +101 -0
  207. package/src/rules/files/folderNames.ts +2 -2
  208. package/src/rules/imports/manifest.ts +1 -1
  209. package/src/rules/imports/runtime.ts +1 -1
  210. package/src/rules/react/jsxConditionals.ts +59 -0
  211. package/src/rules/stories/engineOf.ts +2 -1
  212. package/src/rules/stories/namedValues.ts +4 -4
  213. package/src/rules/stories/unitTests.ts +1 -1
  214. package/src/rules/unusedCode.ts +10 -0
@@ -0,0 +1,90 @@
1
+ import { join, posix } from "node:path";
2
+ import { Effect, Result } from "effect";
3
+ import ts from "typescript";
4
+ import type { Finding } from "#rule.ts";
5
+ import type { MarkdownLine } from "./markdownLines.ts";
6
+ import { markdownLinks } from "./markdownLinks.ts";
7
+ import { type Repository, repositoryLink } from "./repositoryLink.ts";
8
+
9
+ export interface LinkContext {
10
+ readonly anchors: (path: string) => Effect.Effect<ReadonlySet<string> | undefined>;
11
+ readonly published: string | undefined;
12
+ readonly repository: Repository | undefined;
13
+ readonly root: string;
14
+ }
15
+
16
+ interface Destination {
17
+ readonly anchor: string | undefined;
18
+ readonly path: string;
19
+ }
20
+
21
+ const SCHEME = /^(?:[a-z][\d+.a-z-]*:|\/\/)/iu;
22
+
23
+ function decoded(text: string): string {
24
+ return Result.getOrElse(
25
+ Result.try(() => decodeURIComponent(text)),
26
+ () => text,
27
+ );
28
+ }
29
+
30
+ function destination(file: string, target: string, repository: Repository | undefined): Destination | undefined {
31
+ if (SCHEME.test(target)) {
32
+ const linked = repositoryLink(target, repository);
33
+ return linked === undefined ? undefined : { anchor: linked.anchor, path: posix.normalize(decoded(linked.path) || ".") };
34
+ }
35
+ const hash = target.indexOf("#");
36
+ const path = decoded(hash === -1 ? target : target.slice(0, hash));
37
+ const anchor = hash === -1 ? undefined : target.slice(hash + 1);
38
+ if (path === "") {
39
+ return { anchor, path: file };
40
+ }
41
+ return { anchor, path: path.startsWith("/") ? posix.normalize(path.slice(1) || ".") : posix.join(posix.dirname(file), path) };
42
+ }
43
+
44
+ function inside(path: string, directory: string): boolean {
45
+ return path === directory || path.startsWith(`${directory}/`);
46
+ }
47
+
48
+ function exampleUrl(repository: Repository | undefined, to: Destination): string {
49
+ const anchor = to.anchor === undefined ? "" : `#${to.anchor}`;
50
+ return repository === undefined ? "" : `, such as https://github.com/${repository.owner}/${repository.name}/blob/HEAD/${to.path}${anchor}`;
51
+ }
52
+
53
+ function placement(context: LinkContext, target: string, to: Destination): string | undefined {
54
+ if (to.path === ".." || to.path.startsWith("../")) {
55
+ return `"${target}" leaves the repository. Link to a file inside it, or use an absolute URL.`;
56
+ }
57
+ const absolute = join(context.root, to.path);
58
+ if (!(ts.sys.fileExists(absolute) || ts.sys.directoryExists(absolute))) {
59
+ return `"${target}" links to ${to.path}, which does not exist. Link to the file's current path, or remove the link.`;
60
+ }
61
+ if (context.published !== undefined && !SCHEME.test(target) && !inside(to.path, context.published)) {
62
+ return `"${target}" leaves its package, and npm shows ${context.published}/README.md without the repository around it. Use an absolute URL${exampleUrl(context.repository, to)}.`;
63
+ }
64
+ return undefined;
65
+ }
66
+
67
+ function problem(context: LinkContext, target: string, to: Destination): Effect.Effect<string | undefined> {
68
+ const misplaced = placement(context, target, to);
69
+ const anchor = to.anchor;
70
+ if (misplaced !== undefined || anchor === undefined || anchor === "" || !to.path.endsWith(".md")) {
71
+ return Effect.succeed(misplaced);
72
+ }
73
+ return Effect.map(context.anchors(to.path), (anchors) =>
74
+ anchors === undefined || anchors.has(decoded(anchor).toLowerCase())
75
+ ? undefined
76
+ : `"${target}" links to the heading #${anchor}, which ${to.path} does not have. Link to a current heading; GitHub forms its anchor from the heading text.`,
77
+ );
78
+ }
79
+
80
+ export function linkFindings(context: LinkContext, file: string, lines: readonly MarkdownLine[]): Effect.Effect<readonly Finding[]> {
81
+ return Effect.map(
82
+ Effect.forEach(markdownLinks(lines), (link) => {
83
+ const to = destination(file, link.target, context.repository);
84
+ return Effect.map(to === undefined ? Effect.succeed(undefined) : problem(context, link.target, to), (message): readonly Finding[] =>
85
+ message === undefined ? [] : [{ file, line: link.line, message, subject: link.target }],
86
+ );
87
+ }),
88
+ (findings) => findings.flat(),
89
+ );
90
+ }
@@ -0,0 +1,56 @@
1
+ import { linesOf } from "#inventory/linesOf.ts";
2
+
3
+ export type MarkdownLineKind = "code" | "fence" | "prose";
4
+
5
+ export interface MarkdownLine {
6
+ readonly kind: MarkdownLineKind;
7
+ readonly language: string;
8
+ readonly number: number;
9
+ readonly text: string;
10
+ }
11
+
12
+ interface OpenFence {
13
+ readonly language: string;
14
+ readonly marker: string;
15
+ }
16
+
17
+ const FENCE = /^ {0,3}(?<marker>`{3,}|~{3,})\s*(?<info>[^`\s]*)[^`]*$/u;
18
+
19
+ function opening(text: string): OpenFence | undefined {
20
+ const match = FENCE.exec(text);
21
+ const marker = match?.groups?.marker;
22
+ return marker === undefined ? undefined : { language: (match?.groups?.info ?? "").toLowerCase(), marker };
23
+ }
24
+
25
+ function closes(text: string, open: OpenFence): boolean {
26
+ const trimmed = text.trim();
27
+ return trimmed.startsWith(open.marker) && /^(?:`+|~+)$/u.test(trimmed);
28
+ }
29
+
30
+ export function markdownLines(markdown: string): readonly MarkdownLine[] {
31
+ const lines: MarkdownLine[] = [];
32
+ let open: OpenFence | undefined;
33
+ for (const [index, text] of linesOf(markdown).entries()) {
34
+ const number = index + 1;
35
+ if (open === undefined) {
36
+ open = opening(text);
37
+ lines.push({ kind: open === undefined ? "prose" : "fence", language: "", number, text });
38
+ } else if (closes(text, open)) {
39
+ lines.push({ kind: "fence", language: open.language, number, text });
40
+ open = undefined;
41
+ } else {
42
+ lines.push({ kind: "code", language: open.language, number, text });
43
+ }
44
+ }
45
+ return lines;
46
+ }
47
+
48
+ const CODE_SPAN = /(?<ticks>`+)(?<code>.+?)\k<ticks>/gu;
49
+
50
+ export function codeSpans(text: string): readonly string[] {
51
+ return [...text.matchAll(CODE_SPAN)].map((match) => (match.groups?.code ?? "").trim());
52
+ }
53
+
54
+ export function withoutCodeSpans(text: string): string {
55
+ return text.replace(CODE_SPAN, "");
56
+ }
@@ -0,0 +1,33 @@
1
+ import { type MarkdownLine, withoutCodeSpans } from "./markdownLines.ts";
2
+
3
+ export interface MarkdownLink {
4
+ readonly line: number;
5
+ readonly target: string;
6
+ }
7
+
8
+ const INLINE = /\]\(\s*(?<target><[^>]*>|[^\s)]+)/gu;
9
+
10
+ const DEFINITION = /^ {0,3}\[[^\]]+\]:\s*(?<target><[^>]*>|\S+)/u;
11
+
12
+ const ATTRIBUTE = /\b(?:href|src)="(?<target>[^"]+)"/gu;
13
+
14
+ function unwrapped(target: string): string {
15
+ return target.startsWith("<") && target.endsWith(">") ? target.slice(1, -1) : target;
16
+ }
17
+
18
+ function targetsIn(text: string): readonly string[] {
19
+ const prose = withoutCodeSpans(text);
20
+ const definition = DEFINITION.exec(prose)?.groups?.target;
21
+ return [
22
+ ...[...prose.matchAll(INLINE)].map((match) => match.groups?.target ?? ""),
23
+ ...(definition === undefined ? [] : [definition]),
24
+ ...[...prose.matchAll(ATTRIBUTE)].map((match) => match.groups?.target ?? ""),
25
+ ].map(unwrapped);
26
+ }
27
+
28
+ export function markdownLinks(lines: readonly MarkdownLine[]): readonly MarkdownLink[] {
29
+ return lines
30
+ .filter((line) => line.kind === "prose")
31
+ .flatMap((line) => targetsIn(line.text).map((target) => ({ line: line.number, target })))
32
+ .filter((link) => link.target !== "");
33
+ }
@@ -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 { type Endpoint, packageNameOf } from "#imports/resolve.ts";
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, type Endpoint, packageNameOf } from "#imports/resolve.ts";
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 blockedExport(exports: unknown, subpath: string): boolean {
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 false;
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[1] === null;
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
- const best = matching.toSorted(([left], [right]) => right.indexOf("*") - left.indexOf("*") || right.length - left.length)[0];
21
- return best?.[1] === null;
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
+ }
@@ -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
  }
@@ -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,
@@ -0,0 +1,4 @@
1
+ export function linesOf(text: string): readonly string[] {
2
+ const lines = text.split("\n");
3
+ return lines.at(-1) === "" ? lines.slice(0, -1) : lines;
4
+ }
@@ -5,6 +5,10 @@ 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";
10
+ import { effectBoundary } from "#rules/effect/boundary.ts";
11
+ import { serviceParameters } from "#rules/effect/serviceParameters.ts";
8
12
  import { distinctCase } from "#rules/files/distinctCase.ts";
9
13
  import { folderNames } from "#rules/files/folderNames.ts";
10
14
  import { namedAfterExport } from "#rules/files/namedAfterExport.ts";
@@ -16,6 +20,7 @@ import { importsManifest } from "#rules/imports/manifest.ts";
16
20
  import { noTestCode } from "#rules/imports/noTestCode.ts";
17
21
  import { importsResolvable } from "#rules/imports/resolvable.ts";
18
22
  import { importsRuntime } from "#rules/imports/runtime.ts";
23
+ import { jsxConditionals } from "#rules/react/jsxConditionals.ts";
19
24
  import { authSql } from "#rules/stories/authSql.ts";
20
25
  import { storyEngine } from "#rules/stories/engine.ts";
21
26
  import { httpStatus } from "#rules/stories/httpStatus.ts";
@@ -41,8 +46,13 @@ import { manifestsSourceFirst } from "./manifestsSourceFirst.ts";
41
46
  import { maxDepth } from "./maxDepth.ts";
42
47
  import { maxLines } from "./maxLines.ts";
43
48
  import { noBarrel } from "./noBarrel.ts";
49
+ import { unusedCode } from "./unusedCode.ts";
44
50
 
45
51
  export const builtInRules = [
52
+ unusedCode,
53
+ effectBoundary,
54
+ serviceParameters,
55
+ jsxConditionals,
46
56
  maxLines,
47
57
  maxDepth,
48
58
  noBarrel,
@@ -53,6 +63,8 @@ export const builtInRules = [
53
63
  noTodo,
54
64
  noEnvironmentPragma,
55
65
  maxPerFile,
66
+ docsReferences,
67
+ docsUnversionedInstalls,
56
68
  noInline,
57
69
  noDoubleCast,
58
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
+ });
@@ -0,0 +1,75 @@
1
+ import ts from "typescript";
2
+ import { defineRule, type Finding } from "#rule.ts";
3
+ import { parse } from "#rules/parse.ts";
4
+
5
+ function asyncConstruct(node: ts.Node): string | undefined {
6
+ if (
7
+ !(ts.isFunctionLike(node) && ts.canHaveModifiers(node) && ts.getModifiers(node)?.some((modifier) => modifier.kind === ts.SyntaxKind.AsyncKeyword))
8
+ ) {
9
+ return undefined;
10
+ }
11
+ if (ts.isArrowFunction(node)) {
12
+ return "async arrow";
13
+ }
14
+ return ts.isMethodDeclaration(node) ? "async method" : "async function";
15
+ }
16
+
17
+ function thenCall(node: ts.Node): boolean {
18
+ if (!ts.isCallExpression(node)) {
19
+ return false;
20
+ }
21
+ const callee = node.expression;
22
+ return (
23
+ (ts.isPropertyAccessExpression(callee) && callee.name.text === "then")
24
+ || (ts.isElementAccessExpression(callee) && ts.isStringLiteral(callee.argumentExpression) && callee.argumentExpression.text === "then")
25
+ );
26
+ }
27
+
28
+ function construct(node: ts.Node): string | undefined {
29
+ if (ts.isVariableDeclarationList(node) && (node.flags & ts.NodeFlags.AwaitUsing) === ts.NodeFlags.AwaitUsing) {
30
+ return "await";
31
+ }
32
+ if (ts.isAwaitExpression(node) || (ts.isForOfStatement(node) && node.awaitModifier !== undefined)) {
33
+ return "await";
34
+ }
35
+ if (ts.isNewExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === "Promise") {
36
+ return "new Promise(...)";
37
+ }
38
+ if (thenCall(node)) {
39
+ return ".then(...)";
40
+ }
41
+ if (ts.isTryStatement(node)) {
42
+ return "try statement";
43
+ }
44
+ return ts.isThrowStatement(node) ? "throw statement" : asyncConstruct(node);
45
+ }
46
+
47
+ export const effectBoundary = defineRule({
48
+ check: ({ sources }) =>
49
+ sources.flatMap((file) => {
50
+ if (/(?:^|\/)(?:adapters|test-support)\//u.test(file.path)) {
51
+ return [];
52
+ }
53
+ const source = parse(file);
54
+ const findings: Finding[] = [];
55
+ function visit(node: ts.Node): void {
56
+ const name = construct(node);
57
+ if (name !== undefined && source !== undefined) {
58
+ findings.push({
59
+ file: file.path,
60
+ line: source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1,
61
+ message: `Uses ${name}. Model the work with Effect; fail with a tagged error (or Effect.die for a defect). Move a bridge to an outside library into an adapters/ folder, returning Effect values.`,
62
+ });
63
+ }
64
+ ts.forEachChild(node, visit);
65
+ }
66
+ if (source !== undefined) {
67
+ visit(source);
68
+ }
69
+ return findings;
70
+ }),
71
+ description:
72
+ "All checked source, tooling and specs use Effect instead of async, await, new Promise, .then, try or throw. Only adapters/ and test-support/ folders at any depth are exempt. adapters/ bridges outside libraries to Effect; it remains subject to service-parameter and ambient runtime bans. Use tagged errors or Effect.die for defects. Config exceptions and inline suppressions are refused; baseline existing debt.",
73
+ id: "effect/boundary",
74
+ registrable: false,
75
+ });