@alauda/doom 2.6.0 → 2.6.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.
@@ -6,7 +6,7 @@ import { lintRule } from 'unified-lint-rule';
6
6
  import { visit } from 'unist-util-visit';
7
7
  import { visitParents } from 'unist-util-visit-parents';
8
8
  import { isDoc } from "../cli/helpers.js";
9
- import { mdProcessor, mdxProcessor } from "../plugins/index.js";
9
+ import { syntaxProcessor } from "./syntax-plugins.js";
10
10
  import { getConfig } from "./utils.js";
11
11
  const anchorsCache = new Map();
12
12
  const astCache = new Map();
@@ -30,7 +30,11 @@ const getAnchors = (filepath) => {
30
30
  const anchors = new Set();
31
31
  let ast = astCache.get(filepath);
32
32
  if (!ast) {
33
- const processor = filepath.endsWith('.mdx') ? mdxProcessor : mdProcessor;
33
+ // The same stack the lint pipeline uses, so a document's anchors do not
34
+ // depend on whether this run happened to lint it before reading it.
35
+ const processor = filepath.endsWith('.mdx')
36
+ ? syntaxProcessor.mdx
37
+ : syntaxProcessor.md;
34
38
  ast = processor.parse(fs.readFileSync(filepath, 'utf-8'));
35
39
  astCache.set(filepath, ast);
36
40
  }
@@ -10,8 +10,7 @@ import type { Plugin } from 'unified';
10
10
  * register it twice.
11
11
  */
12
12
  type Rule = Plugin<[], never>;
13
- /** Syntax plugins every rule needs before it can run. */
14
- export declare const SYNTAX_PLUGINS: Rule[];
13
+ export { SYNTAX_PLUGINS } from './syntax-plugins.ts';
15
14
  /**
16
15
  * Rules that compare a translation with the source it was made from.
17
16
  *
@@ -72,4 +71,3 @@ export declare const LINT_RULES: Rule[];
72
71
  * position, which some of the orderings above depend on.
73
72
  */
74
73
  export declare const TRANSLATION_CHECK_RULES: Rule[];
75
- export {};
@@ -1,6 +1,3 @@
1
- import remarkDirective from 'remark-directive';
2
- import remarkFrontmatter from 'remark-frontmatter';
3
- import remarkGfm from 'remark-gfm';
4
1
  // @ts-expect-error -- https://github.com/ilyatitovich/remark-lint-code-block-split-list/issues/2
5
2
  import remarkLintCodeBlockSplitList from 'remark-lint-code-block-split-list';
6
3
  import remarkLintHeadingIncrement from 'remark-lint-heading-increment';
@@ -11,12 +8,9 @@ import remarkLintNoChinesePunctuationInNumber from 'remark-lint-no-chinese-punct
11
8
  import remarkLintNoDuplicateHeadingsInSection from 'remark-lint-no-duplicate-headings-in-section';
12
9
  import remarkLintNoHiddenTableCell from 'remark-lint-no-hidden-table-cell';
13
10
  import { checkDeadLinks, chineseTypographyOnlyInChinese, headingAnchorFormat, noDeepHeading, noDeepList, noLegacyOSNames, noMultiOpenAPIPaths, noParagraphIndent, noUnmatchedAnchor, noUnopenedFrontmatter, noUnparsedEmphasis, noUnresolvedApiRef, site, tableSize, titleRequired, translationComponentMultiset, translationEchoedSource, translationFrontmatterPreservation, translationHeadingSequence, translationJsxAttributeParity, translationLengthRatio, translationLinkIsomorphism, translationUpToDate, translationUrlResidue, unitCase, } from "./index.js";
14
- /** Syntax plugins every rule needs before it can run. */
15
- export const SYNTAX_PLUGINS = [
16
- remarkDirective,
17
- remarkFrontmatter,
18
- remarkGfm,
19
- ];
11
+ // The syntax stack lives in its own module so `translation-parity` can parse
12
+ // the source side with it without importing the rules that import it back.
13
+ export { SYNTAX_PLUGINS } from "./syntax-plugins.js";
20
14
  /**
21
15
  * Rules that compare a translation with the source it was made from.
22
16
  *
@@ -0,0 +1,32 @@
1
+ import type { Root } from 'mdast';
2
+ import type { Plugin } from 'unified';
3
+ /**
4
+ * The syntax extensions a document is parsed with, in one place.
5
+ *
6
+ * This exists because the `translation-parity` rules compare two trees, and for
7
+ * a comparison to mean anything both trees have to have been parsed the same
8
+ * way. They were not: the document being linted came through the lint pipeline
9
+ * (these plugins), while the source it was compared against was parsed with the
10
+ * site's `mdxProcessor`, which has no `remark-directive`. Anything directive
11
+ * syntax touches — a port in `http://host:8080`, a tag in `image:1.25`, a time
12
+ * in `10:30` — then became a `textDirective` on one side and stayed plain text
13
+ * on the other, and the rules reported the difference as damage the translator
14
+ * could not repair, because nothing it could write would make the two sides
15
+ * agree.
16
+ *
17
+ * `remark-directive` is in the list because the site renders with it
18
+ * (`plugins/directives`), so it is what the published page actually is.
19
+ */
20
+ export declare const SYNTAX_PLUGINS: Plugin<[], never>[];
21
+ /** Parse-only view of the stack — the rules never stringify the source. */
22
+ export interface SyntaxProcessor {
23
+ parse: (content: string) => Root;
24
+ }
25
+ /**
26
+ * Parses a document exactly as the lint pipeline does — the reference side of
27
+ * every `translation-parity` comparison.
28
+ */
29
+ export declare const syntaxProcessor: {
30
+ md: SyntaxProcessor;
31
+ mdx: SyntaxProcessor;
32
+ };
@@ -0,0 +1,46 @@
1
+ import remarkDirective from 'remark-directive';
2
+ import remarkFrontmatter from 'remark-frontmatter';
3
+ import remarkGfm from 'remark-gfm';
4
+ import remarkMdx from 'remark-mdx';
5
+ import remarkParse from 'remark-parse';
6
+ import { unified } from 'unified';
7
+ /**
8
+ * The syntax extensions a document is parsed with, in one place.
9
+ *
10
+ * This exists because the `translation-parity` rules compare two trees, and for
11
+ * a comparison to mean anything both trees have to have been parsed the same
12
+ * way. They were not: the document being linted came through the lint pipeline
13
+ * (these plugins), while the source it was compared against was parsed with the
14
+ * site's `mdxProcessor`, which has no `remark-directive`. Anything directive
15
+ * syntax touches — a port in `http://host:8080`, a tag in `image:1.25`, a time
16
+ * in `10:30` — then became a `textDirective` on one side and stayed plain text
17
+ * on the other, and the rules reported the difference as damage the translator
18
+ * could not repair, because nothing it could write would make the two sides
19
+ * agree.
20
+ *
21
+ * `remark-directive` is in the list because the site renders with it
22
+ * (`plugins/directives`), so it is what the published page actually is.
23
+ */
24
+ export const SYNTAX_PLUGINS = [
25
+ remarkDirective,
26
+ remarkFrontmatter,
27
+ remarkGfm,
28
+ ];
29
+ const build = (mdx) => {
30
+ let processor = unified().use(remarkParse);
31
+ for (const plugin of SYNTAX_PLUGINS) {
32
+ processor = processor.use(plugin);
33
+ }
34
+ if (mdx) {
35
+ processor = processor.use(remarkMdx);
36
+ }
37
+ return processor.freeze();
38
+ };
39
+ /**
40
+ * Parses a document exactly as the lint pipeline does — the reference side of
41
+ * every `translation-parity` comparison.
42
+ */
43
+ export const syntaxProcessor = {
44
+ md: build(false),
45
+ mdx: build(true),
46
+ };
@@ -1,4 +1,12 @@
1
1
  import type { Root } from 'mdast';
2
+ export declare const partitionAbsorbed: (missing: readonly string[], extra: readonly string[]) => {
3
+ absorbed: {
4
+ target: string;
5
+ suffix: string;
6
+ }[];
7
+ lost: string[];
8
+ unmatched: string[];
9
+ };
2
10
  /**
3
11
  * A translation points at exactly the same places its source points at.
4
12
  *
@@ -4,6 +4,38 @@ const preview = (values) => values
4
4
  .slice(0, 5)
5
5
  .map((value) => `\`${value}\``)
6
6
  .join(', ') + (values.length > 5 ? `, … (${values.length} total)` : '');
7
+ /**
8
+ * A bare URL ends where markdown says it ends, and markdown does not know
9
+ * about Chinese sentence punctuation.
10
+ *
11
+ * GFM closes an autolink literal at whitespace and drops *ASCII* trailing
12
+ * punctuation, so `see http://h:8080.` links to `http://h:8080`. A full-width
13
+ * stop is not ASCII: it is absorbed, and `例如 http://h:8080。` links to
14
+ * `http://h:8080。`, an address that does not exist. The translator writes
15
+ * correct Chinese and gets a broken link for it — and the two messages it used
16
+ * to get, "lost this target" and "points at that one", never said which of the
17
+ * two spellings was the one to change, so the repair loop could only guess.
18
+ *
19
+ * Only a non-ASCII suffix is read this way. `https://x.com` becoming
20
+ * `https://x.com/docs` is also a prefix, and that one is a real retarget.
21
+ */
22
+ const isAbsorbedSuffix = (suffix) => suffix.length > 0 && suffix.codePointAt(0) > 0x7f;
23
+ export const partitionAbsorbed = (missing, extra) => {
24
+ const unmatched = [...extra];
25
+ const lost = [];
26
+ const absorbed = [];
27
+ for (const target of missing) {
28
+ const index = unmatched.findIndex((candidate) => candidate.startsWith(target) &&
29
+ isAbsorbedSuffix(candidate.slice(target.length)));
30
+ if (index === -1) {
31
+ lost.push(target);
32
+ continue;
33
+ }
34
+ absorbed.push({ target, suffix: unmatched[index].slice(target.length) });
35
+ unmatched.splice(index, 1);
36
+ }
37
+ return { absorbed, lost, unmatched };
38
+ };
7
39
  /**
8
40
  * A translation points at exactly the same places its source points at.
9
41
  *
@@ -36,10 +68,14 @@ export const translationLinkIsomorphism = lintRule('doom-lint:translation-link-i
36
68
  const expected = collectLinkTargets(pair.sourceTree, docDirInRoot(pair.sourceLang, pair.relativePath));
37
69
  const actual = collectLinkTargets(tree, docDirInRoot(pair.targetLang, pair.relativePath));
38
70
  const { missing, extra } = diffMultiset(expected, actual);
39
- if (missing.length) {
40
- vfile.message(`Translation lost ${missing.length} link target(s) the source has: ${preview(missing)}.`, tree);
71
+ const { absorbed, lost, unmatched } = partitionAbsorbed(missing, extra);
72
+ for (const { target, suffix } of absorbed) {
73
+ vfile.message(`Translation link \`${target}${suffix}\` swallowed the \`${suffix}\` that follows it: a bare URL runs on until a space, and markdown only leaves out trailing ASCII punctuation. Write it as \`[${target}](${target})\` so the punctuation stays outside the link.`, tree);
74
+ }
75
+ if (lost.length) {
76
+ vfile.message(`Translation lost ${lost.length} link target(s) the source has: ${preview(lost)}.`, tree);
41
77
  }
42
- if (extra.length) {
43
- vfile.message(`Translation points at ${extra.length} target(s) the source does not: ${preview(extra)}.`, tree);
78
+ if (unmatched.length) {
79
+ vfile.message(`Translation points at ${unmatched.length} target(s) the source does not: ${preview(unmatched)}.`, tree);
44
80
  }
45
81
  });
@@ -5,8 +5,8 @@ import picomatch from 'picomatch';
5
5
  import { visit } from 'unist-util-visit';
6
6
  import { parse as parseYaml } from 'yaml';
7
7
  import { escapeMarkdownHeadingIds } from "../../cli/helpers.js";
8
- import { mdProcessor, mdxProcessor } from "../../plugins/index.js";
9
8
  import { DEFAULT_COPY_ONLY_DIRECTORIES, SUPPORTED_LANGUAGES, } from "../../shared/index.js";
9
+ import { syntaxProcessor } from "../syntax-plugins.js";
10
10
  import { getConfig } from "../utils.js";
11
11
  const matcherCache = new Map();
12
12
  /** Memoised, because it is asked once per document and the patterns never change. */
@@ -36,7 +36,11 @@ const loadSource = async (sourcePath) => {
36
36
  if (cached?.sha === sha) {
37
37
  return cached;
38
38
  }
39
- const processor = sourcePath.endsWith('.mdx') ? mdxProcessor : mdProcessor;
39
+ // The same syntax stack the document being linted came through: a
40
+ // comparison between two differently-parsed trees measures the parsers.
41
+ const processor = sourcePath.endsWith('.mdx')
42
+ ? syntaxProcessor.mdx
43
+ : syntaxProcessor.md;
40
44
  // The same escaping `doom translate` applies before parsing: without it a
41
45
  // custom heading anchor is an MDX expression and the parse fails outright.
42
46
  const entry = {
@@ -1,2 +1,3 @@
1
1
  import type { Root } from 'mdast';
2
+ export declare const collectProseUrls: (tree: Root) => string[];
2
3
  export declare const translationUrlResidue: import("unified-lint-rule").Plugin<Root, unknown>;
@@ -1,5 +1,5 @@
1
1
  import { lintRule } from 'unified-lint-rule';
2
- import { visit } from 'unist-util-visit';
2
+ import { SKIP, visit } from 'unist-util-visit';
3
3
  import { currentPair, diffMultiset } from "./shared.js";
4
4
  /**
5
5
  * URLs written in prose that markdown does not turn into links still survive
@@ -24,9 +24,30 @@ import { currentPair, diffMultiset } from "./shared.js";
24
24
  * is a guard for a case nothing else covers, not a demonstrated detector.
25
25
  */
26
26
  const BARE_URL = /\b(?:[a-z][a-z0-9+.-]*:\/\/|www\.)\S+/gi;
27
- const collect = (tree) => {
27
+ /**
28
+ * Text inside a link is not prose for this purpose.
29
+ *
30
+ * The rule's whole premise is that a URL markdown *did* turn into a link is
31
+ * protected structurally and belongs to `link-isomorphism`. The first
32
+ * implementation still walked into link nodes, so an autolink counted twice:
33
+ * once as a target and once as the label text that repeats it. That is not
34
+ * merely redundant. A translator that writes `[http://host:8080](http://host:8080)`
35
+ * — the one spelling of a bare URL that Chinese sentence punctuation cannot
36
+ * corrupt — had its label read as prose, found the URL missing from it (the
37
+ * port is a `textDirective` there), and was told it had lost a URL it had in
38
+ * fact preserved exactly. No spelling it could reach satisfied both rules, so
39
+ * the repair loop could only run out of rounds.
40
+ */
41
+ const IS_LINK = new Set(['link', 'linkReference', 'definition']);
42
+ export const collectProseUrls = (tree) => {
28
43
  const found = [];
29
- visit(tree, 'text', (node) => {
44
+ visit(tree, (node) => {
45
+ if (IS_LINK.has(node.type)) {
46
+ return SKIP;
47
+ }
48
+ if (node.type !== 'text') {
49
+ return;
50
+ }
30
51
  for (const [match] of node.value.matchAll(BARE_URL)) {
31
52
  found.push(match);
32
53
  }
@@ -38,7 +59,7 @@ export const translationUrlResidue = lintRule('doom-lint:translation-url-residue
38
59
  if (!pair) {
39
60
  return;
40
61
  }
41
- const { missing } = diffMultiset(collect(pair.sourceTree), collect(tree));
62
+ const { missing } = diffMultiset(collectProseUrls(pair.sourceTree), collectProseUrls(tree));
42
63
  if (!missing.length) {
43
64
  return;
44
65
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@alauda/doom",
3
- "version": "2.6.0",
3
+ "version": "2.6.1",
4
4
  "type": "module",
5
5
  "description": "Doctor Doom making docs.",
6
6
  "repository": {