1 ;;; org-lint.el --- Linting for Org documents -*- lexical-binding: t; -*-
3 ;; Copyright (C) 2015-2017 Free Software Foundation
5 ;; Author: Nicolas Goaziou <mail@nicolasgoaziou.fr>
6 ;; Keywords: outlines, hypermedia, calendar, wp
8 ;; This program is free software; you can redistribute it and/or modify
9 ;; it under the terms of the GNU General Public License as published by
10 ;; the Free Software Foundation, either version 3 of the License, or
11 ;; (at your option) any later version.
13 ;; This program is distributed in the hope that it will be useful,
14 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
15 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 ;; GNU General Public License for more details.
18 ;; You should have received a copy of the GNU General Public License
19 ;; along with this program. If not, see <http://www.gnu.org/licenses/>.
23 ;; This library implements linting for Org syntax. The sole public
24 ;; function is `org-lint', which see.
26 ;; Internally, the library defines a new structure:
27 ;; `org-lint-checker', with the following slots:
29 ;; - NAME: Unique check identifier, as a non-nil symbol that doesn't
30 ;; start with an hyphen.
32 ;; The check is done calling the function `org-lint-NAME' with one
33 ;; mandatory argument, the parse tree describing the current Org
34 ;; buffer. Such function calls are wrapped within
35 ;; a `save-excursion' and point is always at `point-min'. Its
36 ;; return value has to be an alist (POSITION MESSAGE) when
37 ;; POSITION refer to the buffer position of the error, as an
38 ;; integer, and MESSAGE is a string describing the error.
40 ;; - DESCRIPTION: Summary about the check, as a string.
42 ;; - CATEGORIES: Categories relative to the check, as a list of
43 ;; symbol. They are used for filtering when calling `org-lint'.
44 ;; Checkers not explicitly associated to a category are collected
45 ;; in the `default' one.
47 ;; - TRUST: The trust level one can have in the check. It is either
48 ;; `low' or `high', depending on the heuristics implemented and
49 ;; the nature of the check. This has an indicative value only and
50 ;; is displayed along reports.
52 ;; All checks have to be listed in `org-lint--checkers'.
54 ;; Results are displayed in a special "*Org Lint*" buffer with
55 ;; a dedicated major mode, derived from `tabulated-list-mode'.
57 ;; In addition to the usual key-bindings inherited from it, "C-j" and
58 ;; "TAB" display problematic line reported under point whereas "RET"
59 ;; jumps to it. Also, "h" hides all reports similar to the current
60 ;; one. Additionally, "i" removes them from subsequent reports.
62 ;; Checks currently implemented are:
64 ;; - duplicate CUSTOM_ID properties
65 ;; - duplicate NAME values
66 ;; - duplicate targets
67 ;; - duplicate footnote definitions
68 ;; - orphaned affiliated keywords
69 ;; - obsolete affiliated keywords
70 ;; - missing language in src blocks
71 ;; - missing back-end in export blocks
72 ;; - invalid Babel call blocks
73 ;; - NAME values with a colon
74 ;; - deprecated export block syntax
75 ;; - deprecated Babel header properties
76 ;; - wrong header arguments in src blocks
77 ;; - misuse of CATEGORY keyword
78 ;; - "coderef" links with unknown destination
79 ;; - "custom-id" links with unknown destination
80 ;; - "fuzzy" links with unknown destination
81 ;; - "id" links with unknown destination
82 ;; - links to non-existent local files
83 ;; - SETUPFILE keywords with non-existent file parameter
84 ;; - INCLUDE keywords with wrong link parameter
85 ;; - obsolete markup in INCLUDE keyword
86 ;; - unknown items in OPTIONS keyword
87 ;; - spurious macro arguments or invalid macro templates
88 ;; - special properties in properties drawer
89 ;; - obsolete syntax for PROPERTIES drawers
90 ;; - Invalid EFFORT property value
91 ;; - missing definition for footnote references
92 ;; - missing reference for footnote definitions
93 ;; - non-footnote definitions in footnote section
94 ;; - probable invalid keywords
96 ;; - misplaced planning info line
97 ;; - incomplete drawers
98 ;; - indented diary-sexps
99 ;; - obsolete QUOTE section
100 ;; - obsolete "file+application" link
101 ;; - blank headlines with tags
107 (require 'org-element
)
115 (cl-defstruct (org-lint-checker (:copier nil
))
116 (name 'missing-checker-name
)
118 (categories '(default))
119 (trust 'high
)) ; `low' or `high'
121 (defun org-lint-missing-checker-name (_)
123 "`A checker has no `:name' property. Please verify `org-lint--checkers'"))
125 (defconst org-lint--checkers
127 (make-org-lint-checker
128 :name
'duplicate-custom-id
129 :description
"Report duplicates CUSTOM_ID properties"
131 (make-org-lint-checker
132 :name
'duplicate-name
133 :description
"Report duplicate NAME values"
134 :categories
'(babel link
))
135 (make-org-lint-checker
136 :name
'duplicate-target
137 :description
"Report duplicate targets"
139 (make-org-lint-checker
140 :name
'duplicate-footnote-definition
141 :description
"Report duplicate footnote definitions"
142 :categories
'(footnote))
143 (make-org-lint-checker
144 :name
'orphaned-affiliated-keywords
145 :description
"Report orphaned affiliated keywords"
147 (make-org-lint-checker
148 :name
'obsolete-affiliated-keywords
149 :description
"Report obsolete affiliated keywords"
150 :categories
'(obsolete))
151 (make-org-lint-checker
152 :name
'deprecated-export-blocks
153 :description
"Report deprecated export block syntax"
154 :categories
'(obsolete export
)
156 (make-org-lint-checker
157 :name
'deprecated-header-syntax
158 :description
"Report deprecated Babel header syntax"
159 :categories
'(obsolete babel
)
161 (make-org-lint-checker
162 :name
'missing-language-in-src-block
163 :description
"Report missing language in src blocks"
164 :categories
'(babel))
165 (make-org-lint-checker
166 :name
'missing-backend-in-export-block
167 :description
"Report missing back-end in export blocks"
168 :categories
'(export))
169 (make-org-lint-checker
170 :name
'invalid-babel-call-block
171 :description
"Report invalid Babel call blocks"
172 :categories
'(babel))
173 (make-org-lint-checker
175 :description
"Report NAME values with a colon"
176 :categories
'(babel))
177 (make-org-lint-checker
178 :name
'wrong-header-argument
179 :description
"Report wrong babel headers"
180 :categories
'(babel))
181 (make-org-lint-checker
182 :name
'wrong-header-value
183 :description
"Report invalid value in babel headers"
186 (make-org-lint-checker
187 :name
'deprecated-category-setup
188 :description
"Report misuse of CATEGORY keyword"
189 :categories
'(obsolete))
190 (make-org-lint-checker
191 :name
'invalid-coderef-link
192 :description
"Report \"coderef\" links with unknown destination"
194 (make-org-lint-checker
195 :name
'invalid-custom-id-link
196 :description
"Report \"custom-id\" links with unknown destination"
198 (make-org-lint-checker
199 :name
'invalid-fuzzy-link
200 :description
"Report \"fuzzy\" links with unknown destination"
202 (make-org-lint-checker
203 :name
'invalid-id-link
204 :description
"Report \"id\" links with unknown destination"
206 (make-org-lint-checker
207 :name
'link-to-local-file
208 :description
"Report links to non-existent local files"
211 (make-org-lint-checker
212 :name
'non-existent-setupfile-parameter
213 :description
"Report SETUPFILE keywords with non-existent file parameter"
215 (make-org-lint-checker
216 :name
'wrong-include-link-parameter
217 :description
"Report INCLUDE keywords with misleading link parameter"
218 :categories
'(export)
220 (make-org-lint-checker
221 :name
'obsolete-include-markup
222 :description
"Report obsolete markup in INCLUDE keyword"
223 :categories
'(obsolete export
)
225 (make-org-lint-checker
226 :name
'unknown-options-item
227 :description
"Report unknown items in OPTIONS keyword"
228 :categories
'(export)
230 (make-org-lint-checker
231 :name
'invalid-macro-argument-and-template
232 :description
"Report spurious macro arguments or invalid macro templates"
233 :categories
'(export)
235 (make-org-lint-checker
236 :name
'special-property-in-properties-drawer
237 :description
"Report special properties in properties drawers"
238 :categories
'(properties))
239 (make-org-lint-checker
240 :name
'obsolete-properties-drawer
241 :description
"Report obsolete syntax for properties drawers"
242 :categories
'(obsolete properties
))
243 (make-org-lint-checker
244 :name
'invalid-effort-property
245 :description
"Report invalid duration in EFFORT property"
246 :categories
'(properties))
247 (make-org-lint-checker
248 :name
'undefined-footnote-reference
249 :description
"Report missing definition for footnote references"
250 :categories
'(footnote))
251 (make-org-lint-checker
252 :name
'unreferenced-footnote-definition
253 :description
"Report missing reference for footnote definitions"
254 :categories
'(footnote))
255 (make-org-lint-checker
256 :name
'extraneous-element-in-footnote-section
257 :description
"Report non-footnote definitions in footnote section"
258 :categories
'(footnote))
259 (make-org-lint-checker
260 :name
'invalid-keyword-syntax
261 :description
"Report probable invalid keywords"
263 (make-org-lint-checker
265 :description
"Report invalid blocks"
267 (make-org-lint-checker
268 :name
'misplaced-planning-info
269 :description
"Report misplaced planning info line"
271 (make-org-lint-checker
272 :name
'incomplete-drawer
273 :description
"Report probable incomplete drawers"
275 (make-org-lint-checker
276 :name
'indented-diary-sexp
277 :description
"Report probable indented diary-sexps"
279 (make-org-lint-checker
281 :description
"Report obsolete QUOTE section"
282 :categories
'(obsolete)
284 (make-org-lint-checker
285 :name
'file-application
286 :description
"Report obsolete \"file+application\" link"
287 :categories
'(link obsolete
))
288 (make-org-lint-checker
289 :name
'empty-headline-with-tags
290 :description
"Report ambiguous empty headlines with tags"
291 :categories
'(headline)
293 "List of all available checkers.")
295 (defun org-lint--collect-duplicates
296 (ast type extract-key extract-position build-message
)
297 "Helper function to collect duplicates in parse tree AST.
299 EXTRACT-KEY is a function extracting key. It is called with
300 a single argument: the element or object. Comparison is done
303 EXTRACT-POSITION is a function returning position for the report.
304 It is called with two arguments, the object or element, and the
307 BUILD-MESSAGE is a function creating the report message. It is
308 called with one argument, the key used for comparison."
313 (lambda (position value
)
314 (push (list position
(funcall build-message value
)) reports
))))
315 (org-element-map ast type
317 (let ((key (funcall extract-key datum
)))
320 ((assoc key keys
) (cl-pushnew (assoc key keys
) originals
)
321 (funcall make-report
(funcall extract-position datum key
) key
))
322 (t (push (cons key
(funcall extract-position datum key
)) keys
))))))
323 (dolist (e originals reports
) (funcall make-report
(cdr e
) (car e
)))))
325 (defun org-lint-duplicate-custom-id (ast)
326 (org-lint--collect-duplicates
330 (and (eq (compare-strings "CUSTOM_ID" nil nil
331 (org-element-property :key property
) nil nil
334 (org-element-property :value property
)))
335 (lambda (property _
) (org-element-property :begin property
))
336 (lambda (key) (format "Duplicate CUSTOM_ID property \"%s\"" key
))))
338 (defun org-lint-duplicate-name (ast)
339 (org-lint--collect-duplicates
341 org-element-all-elements
342 (lambda (datum) (org-element-property :name datum
))
344 (goto-char (org-element-property :begin datum
))
346 (format "^[ \t]*#\\+[A-Za-z]+: +%s *$" (regexp-quote name
)))
348 (lambda (key) (format "Duplicate NAME \"%s\"" key
))))
350 (defun org-lint-duplicate-target (ast)
351 (org-lint--collect-duplicates
354 (lambda (target) (org-split-string (org-element-property :value target
)))
355 (lambda (target _
) (org-element-property :begin target
))
357 (format "Duplicate target <<%s>>" (mapconcat #'identity key
" ")))))
359 (defun org-lint-duplicate-footnote-definition (ast)
360 (org-lint--collect-duplicates
363 (lambda (definition) (org-element-property :label definition
))
364 (lambda (definition _
) (org-element-property :post-affiliated definition
))
365 (lambda (key) (format "Duplicate footnote definition \"%s\"" key
))))
367 (defun org-lint-orphaned-affiliated-keywords (ast)
368 ;; Ignore orphan RESULTS keywords, which could be generated from
369 ;; a source block returning no value.
370 (let ((keywords (cl-set-difference org-element-affiliated-keywords
371 '("RESULT" "RESULTS")
373 (org-element-map ast
'keyword
375 (let ((key (org-element-property :key k
)))
376 (and (or (let ((case-fold-search t
))
377 (string-match-p "\\`ATTR_[-_A-Za-z0-9]+\\'" key
))
378 (member key keywords
))
379 (list (org-element-property :post-affiliated k
)
380 (format "Orphaned affiliated keyword: \"%s\"" key
))))))))
382 (defun org-lint-obsolete-affiliated-keywords (_)
383 (let ((regexp (format "^[ \t]*#\\+%s:"
384 (regexp-opt '("DATA" "LABEL" "RESNAME" "SOURCE"
385 "SRCNAME" "TBLNAME" "RESULT" "HEADERS")
388 (while (re-search-forward regexp nil t
)
389 (let ((key (upcase (match-string-no-properties 1))))
391 (org-element-property :post-affiliated
(org-element-at-point)))
393 (list (line-beginning-position)
395 "Obsolete affiliated keyword: \"%s\". Use \"%s\" instead"
404 (defun org-lint-deprecated-export-blocks (ast)
405 (let ((deprecated '("ASCII" "BEAMER" "HTML" "LATEX" "MAN" "MARKDOWN" "MD"
406 "ODT" "ORG" "TEXINFO")))
407 (org-element-map ast
'special-block
409 (let ((type (org-element-property :type b
)))
410 (when (member-ignore-case type deprecated
)
412 (org-element-property :post-affiliated b
)
414 "Deprecated syntax for export block. Use \"BEGIN_EXPORT %s\" \
418 (defun org-lint-deprecated-header-syntax (ast)
419 (let* ((deprecated-babel-properties
420 (mapcar (lambda (arg) (symbol-name (car arg
)))
421 org-babel-common-header-args-w-values
))
423 (format "\\`%s[ \t]" (regexp-opt deprecated-babel-properties t
))))
424 (org-element-map ast
'(keyword node-property
)
426 (let ((key (org-element-property :key datum
)))
427 (pcase (org-element-type datum
)
429 (let ((value (org-element-property :value datum
)))
430 (and (string= key
"PROPERTY")
431 (string-match deprecated-re value
)
432 (list (org-element-property :begin datum
)
433 (format "Deprecated syntax for \"%s\". \
434 Use header-args instead"
435 (match-string-no-properties 1 value
))))))
437 (and (member-ignore-case key deprecated-babel-properties
)
439 (org-element-property :begin datum
)
440 (format "Deprecated syntax for \"%s\". \
441 Use :header-args: instead"
444 (defun org-lint-missing-language-in-src-block (ast)
445 (org-element-map ast
'src-block
447 (unless (org-element-property :language b
)
448 (list (org-element-property :post-affiliated b
)
449 "Missing language in source block")))))
451 (defun org-lint-missing-backend-in-export-block (ast)
452 (org-element-map ast
'export-block
454 (unless (org-element-property :type b
)
455 (list (org-element-property :post-affiliated b
)
456 "Missing back-end in export block")))))
458 (defun org-lint-invalid-babel-call-block (ast)
459 (org-element-map ast
'babel-call
462 ((not (org-element-property :call b
))
463 (list (org-element-property :post-affiliated b
)
464 "Invalid syntax in babel call block"))
465 ((let ((h (org-element-property :end-header b
)))
466 (and h
(string-match-p "\\`\\[.*\\]\\'" h
)))
468 (org-element-property :post-affiliated b
)
469 "Babel call's end header must not be wrapped within brackets"))))))
471 (defun org-lint-deprecated-category-setup (ast)
472 (org-element-map ast
'keyword
476 ((not (string= (org-element-property :key k
) "CATEGORY")) nil
)
478 (list (org-element-property :post-affiliated k
)
479 "Spurious CATEGORY keyword. Set :CATEGORY: property instead"))
480 (t (setf category-flag t
) nil
))))))
482 (defun org-lint-invalid-coderef-link (ast)
483 (let ((info (list :parse-tree ast
)))
484 (org-element-map ast
'link
486 (let ((ref (org-element-property :path link
)))
487 (and (equal (org-element-property :type link
) "coderef")
488 (not (ignore-errors (org-export-resolve-coderef ref info
)))
489 (list (org-element-property :begin link
)
490 (format "Unknown coderef \"%s\"" ref
))))))))
492 (defun org-lint-invalid-custom-id-link (ast)
493 (let ((info (list :parse-tree ast
)))
494 (org-element-map ast
'link
496 (and (equal (org-element-property :type link
) "custom-id")
497 (not (ignore-errors (org-export-resolve-id-link link info
)))
498 (list (org-element-property :begin link
)
499 (format "Unknown custom ID \"%s\""
500 (org-element-property :path link
))))))))
502 (defun org-lint-invalid-fuzzy-link (ast)
503 (let ((info (list :parse-tree ast
)))
504 (org-element-map ast
'link
506 (and (equal (org-element-property :type link
) "fuzzy")
507 (not (ignore-errors (org-export-resolve-fuzzy-link link info
)))
508 (list (org-element-property :begin link
)
509 (format "Unknown fuzzy location \"%s\""
510 (let ((path (org-element-property :path link
)))
511 (if (string-prefix-p "*" path
)
515 (defun org-lint-invalid-id-link (ast)
516 (org-element-map ast
'link
518 (let ((id (org-element-property :path link
)))
519 (and (equal (org-element-property :type link
) "id")
520 (not (org-id-find id
))
521 (list (org-element-property :begin link
)
522 (format "Unknown ID \"%s\"" id
)))))))
524 (defun org-lint-special-property-in-properties-drawer (ast)
525 (org-element-map ast
'node-property
527 (let ((key (org-element-property :key p
)))
528 (and (member-ignore-case key org-special-properties
)
529 (list (org-element-property :begin p
)
531 "Special property \"%s\" found in a properties drawer"
534 (defun org-lint-obsolete-properties-drawer (ast)
535 (org-element-map ast
'drawer
537 (when (equal (org-element-property :drawer-name d
) "PROPERTIES")
538 (let ((section (org-element-lineage d
'(section))))
539 (unless (org-element-map section
'property-drawer
#'identity nil t
)
540 (list (org-element-property :post-affiliated d
)
542 (goto-char (org-element-property :post-affiliated d
))
544 (or (org-at-heading-p) (org-at-planning-p)))
545 "Incorrect contents for PROPERTIES drawer"
546 "Incorrect location for PROPERTIES drawer"))))))))
548 (defun org-lint-invalid-effort-property (ast)
549 (org-element-map ast
'node-property
551 (when (equal "EFFORT" (org-element-property :key p
))
552 (let ((value (org-element-property :value p
)))
553 (and (org-string-nw-p value
)
554 (not (org-duration-p value
))
555 (list (org-element-property :begin p
)
556 (format "Invalid effort duration format: %S" value
))))))))
558 (defun org-lint-link-to-local-file (ast)
559 (org-element-map ast
'link
561 (when (equal (org-element-property :type l
) "file")
562 (let ((file (org-link-unescape (org-element-property :path l
))))
563 (and (not (file-remote-p file
))
564 (not (file-exists-p file
))
565 (list (org-element-property :begin l
)
566 (format (if (org-element-lineage l
'(link))
567 "Link to non-existent image file \"%s\"\
569 "Link to non-existent local file \"%s\"")
572 (defun org-lint-non-existent-setupfile-parameter (ast)
573 (org-element-map ast
'keyword
575 (when (equal (org-element-property :key k
) "SETUPFILE")
576 (let ((file (org-unbracket-string
578 (org-element-property :value k
))))
579 (and (not (file-remote-p file
))
580 (not (file-exists-p file
))
581 (list (org-element-property :begin k
)
582 (format "Non-existent setup file \"%s\"" file
))))))))
584 (defun org-lint-wrong-include-link-parameter (ast)
585 (org-element-map ast
'keyword
587 (when (equal (org-element-property :key k
) "INCLUDE")
588 (let* ((value (org-element-property :value k
))
590 (and (string-match "^\\(\".+\"\\|\\S-+\\)[ \t]*" value
)
592 (org-unbracket-string "\"" "\"" (match-string 1 value
))))))
594 (list (org-element-property :post-affiliated k
)
595 "Missing location argument in INCLUDE keyword")
596 (let* ((file (org-string-nw-p
597 (if (string-match "::\\(.*\\)\\'" path
)
598 (substring path
0 (match-beginning 0))
600 (search (and (not (equal file path
))
601 (org-string-nw-p (match-string 1 path
)))))
603 (not (file-remote-p file
))
604 (not (file-exists-p file
)))
605 (list (org-element-property :post-affiliated k
)
606 "Non-existent file argument in INCLUDE keyword")
607 (let* ((visiting (if file
(find-buffer-visiting file
)
609 (buffer (or visiting
(find-file-noselect file
))))
611 (with-current-buffer buffer
615 (let ((org-link-search-inhibit-query t
))
616 (org-link-search search nil t
)))))
617 (list (org-element-property :post-affiliated k
)
619 "Invalid search part \"%s\" in INCLUDE keyword"
621 (unless visiting
(kill-buffer buffer
))))))))))))
623 (defun org-lint-obsolete-include-markup (ast)
624 (let ((regexp (format "\\`\\(?:\".+\"\\|\\S-+\\)[ \t]+%s"
626 '("ASCII" "BEAMER" "HTML" "LATEX" "MAN" "MARKDOWN" "MD"
627 "ODT" "ORG" "TEXINFO")
629 (org-element-map ast
'keyword
631 (when (equal (org-element-property :key k
) "INCLUDE")
632 (let ((case-fold-search t
)
633 (value (org-element-property :value k
)))
634 (when (string-match regexp value
)
635 (let ((markup (match-string-no-properties 1 value
)))
636 (list (org-element-property :post-affiliated k
)
637 (format "Obsolete markup \"%s\" in INCLUDE keyword. \
638 Use \"export %s\" instead"
642 (defun org-lint-unknown-options-item (ast)
643 (let ((allowed (delq nil
645 (mapcar (lambda (o) (nth 2 o
)) org-export-options-alist
)
648 (mapcar (lambda (o) (nth 2 o
))
649 (org-export-backend-options b
)))
650 org-export-registered-backends
))))
652 (org-element-map ast
'keyword
654 (when (string= (org-element-property :key k
) "OPTIONS")
655 (let ((value (org-element-property :value k
))
657 (while (string-match "\\(.+?\\):\\((.*?)\\|\\S-*\\)[ \t]*"
660 (setf start
(match-end 0))
661 (let ((item (match-string 1 value
)))
662 (unless (member item allowed
)
663 (push (list (org-element-property :post-affiliated k
)
664 (format "Unknown OPTIONS item \"%s\"" item
))
668 (defun org-lint-invalid-macro-argument-and-template (ast)
669 (let ((extract-placeholders
673 (while (string-match "\\$\\([1-9][0-9]*\\)" template start
)
674 (setf start
(match-end 0))
675 (push (string-to-number (match-string 1 template
)) args
))
676 (sort (org-uniquify args
) #'<))))
678 ;; Check arguments for macro templates.
679 (org-element-map ast
'keyword
681 (when (string= (org-element-property :key k
) "MACRO")
682 (let* ((value (org-element-property :value k
))
683 (name (and (string-match "^\\S-+" value
)
684 (match-string 0 value
)))
686 (org-trim (substring value
(match-end 0))))))
689 (push (list (org-element-property :post-affiliated k
)
690 "Missing name in MACRO keyword")
692 ((not (org-string-nw-p template
))
693 (push (list (org-element-property :post-affiliated k
)
694 "Missing template in macro \"%s\"" name
)
697 (unless (let ((args (funcall extract-placeholders template
)))
698 (equal (number-sequence 1 (or (org-last args
) 0)) args
))
699 (push (list (org-element-property :post-affiliated k
)
700 (format "Unused placeholders in macro \"%s\""
703 ;; Check arguments for macros.
704 (org-macro-initialize-templates)
705 (let ((templates (append
706 (mapcar (lambda (m) (cons m
"$1"))
707 '("author" "date" "email" "title" "results"))
708 org-macro-templates
)))
709 (org-element-map ast
'macro
711 (let* ((name (org-element-property :key macro
))
712 (template (cdr (assoc-string name templates t
))))
714 (push (list (org-element-property :begin macro
)
715 (format "Undefined macro \"%s\"" name
))
717 (let ((arg-numbers (funcall extract-placeholders template
)))
720 (nthcdr (apply #'max arg-numbers
)
721 (org-element-property :args macro
))))
724 (list (org-element-property :begin macro
)
725 (format "Unused argument%s in macro \"%s\": %s"
726 (if (> (length spurious-args
) 1) "s" "")
728 (mapconcat (lambda (a) (format "\"%s\"" a
))
734 (defun org-lint-undefined-footnote-reference (ast)
735 (let ((definitions (org-element-map ast
'footnote-definition
736 (lambda (f) (org-element-property :label f
)))))
737 (org-element-map ast
'footnote-reference
739 (let ((label (org-element-property :label f
)))
741 (not (member label definitions
))
742 (list (org-element-property :begin f
)
743 (format "Missing definition for footnote [%s]"
746 (defun org-lint-unreferenced-footnote-definition (ast)
747 (let ((references (org-element-map ast
'footnote-reference
748 (lambda (f) (org-element-property :label f
)))))
749 (org-element-map ast
'footnote-definition
751 (let ((label (org-element-property :label f
)))
753 (not (member label references
))
754 (list (org-element-property :post-affiliated f
)
755 (format "No reference for footnote definition [%s]"
758 (defun org-lint-colon-in-name (ast)
759 (org-element-map ast org-element-all-elements
761 (let ((name (org-element-property :name e
)))
763 (string-match-p ":" name
)
765 (goto-char (org-element-property :begin e
))
767 (format "^[ \t]*#\\+\\w+: +%s *$" (regexp-quote name
)))
770 "Name \"%s\" contains a colon; Babel cannot use it as input"
773 (defun org-lint-misplaced-planning-info (_)
774 (let ((case-fold-search t
)
776 (while (re-search-forward org-planning-line-re nil t
)
777 (unless (memq (org-element-type (org-element-at-point))
778 '(comment-block example-block export-block planning
779 src-block verse-block
))
780 (push (list (line-beginning-position) "Misplaced planning info line")
784 (defun org-lint-incomplete-drawer (_)
786 (while (re-search-forward org-drawer-regexp nil t
)
787 (let ((name (org-trim (match-string-no-properties 0)))
788 (element (org-element-at-point)))
789 (pcase (org-element-type element
)
790 ((or `drawer
`property-drawer
)
791 (goto-char (org-element-property :end element
))
793 ((or `comment-block
`example-block
`export-block
`src-block
797 (push (list (line-beginning-position)
798 (format "Possible incomplete drawer \"%s\"" name
))
802 (defun org-lint-indented-diary-sexp (_)
804 (while (re-search-forward "^[ \t]+%%(" nil t
)
805 (unless (memq (org-element-type (org-element-at-point))
806 '(comment-block diary-sexp example-block export-block
807 src-block verse-block
))
808 (push (list (line-beginning-position) "Possible indented diary-sexp")
812 (defun org-lint-invalid-block (_)
813 (let ((case-fold-search t
)
814 (regexp "^[ \t]*#\\+\\(BEGIN\\|END\\)\\(?::\\|_[^[:space:]]*\\)?[ \t]*")
816 (while (re-search-forward regexp nil t
)
817 (let ((name (org-trim (buffer-substring-no-properties
818 (line-beginning-position) (line-end-position)))))
820 ((and (string-prefix-p "END" (match-string 1) t
)
822 (push (list (line-beginning-position)
823 (format "Invalid block closing line \"%s\"" name
))
825 ((not (memq (org-element-type (org-element-at-point))
826 '(center-block comment-block dynamic-block example-block
827 export-block quote-block special-block
828 src-block verse-block
)))
829 (push (list (line-beginning-position)
830 (format "Possible incomplete block \"%s\""
835 (defun org-lint-invalid-keyword-syntax (_)
836 (let ((regexp "^[ \t]*#\\+\\([^[:space:]:]*\\)\\(?: \\|$\\)")
838 (format "[ \t]*#\\+%s\\(\\[.*\\]\\)?:\\(?: \\|$\\)"
839 (regexp-opt org-element-dual-keywords
)))
841 (while (re-search-forward regexp nil t
)
842 (let ((name (match-string-no-properties 1)))
843 (unless (or (string-prefix-p "BEGIN" name t
)
844 (string-prefix-p "END" name t
)
847 (let ((case-fold-search t
)) (looking-at exception-re
))))
848 (push (list (match-beginning 0)
849 (format "Possible missing colon in keyword \"%s\"" name
))
853 (defun org-lint-extraneous-element-in-footnote-section (ast)
854 (org-element-map ast
'headline
856 (and (org-element-property :footnote-section-p h
)
857 (org-element-map (org-element-contents h
)
860 (memq e
'(comment comment-block footnote-definition
861 property-drawer section
)))
862 org-element-all-elements
)
864 (not (and (eq (org-element-type e
) 'headline
)
865 (org-element-property :commentedp e
))))
866 nil t
'(footnote-definition property-drawer
))
867 (list (org-element-property :begin h
)
868 "Extraneous elements in footnote section are not exported")))))
870 (defun org-lint-quote-section (ast)
871 (org-element-map ast
'(headline inlinetask
)
873 (let ((title (org-element-property :raw-value h
)))
874 (and (or (string-prefix-p "QUOTE " title
)
875 (string-prefix-p (concat org-comment-string
" QUOTE ") title
))
876 (list (org-element-property :begin h
)
877 "Deprecated QUOTE section"))))))
879 (defun org-lint-file-application (ast)
880 (org-element-map ast
'link
882 (let ((app (org-element-property :application l
)))
884 (list (org-element-property :begin l
)
885 (format "Deprecated \"file+%s\" link type" app
)))))))
887 (defun org-lint-wrong-header-argument (ast)
890 (lambda (datum language headers
)
892 ;; If LANGUAGE is specified, restrict allowed
893 ;; headers to both LANGUAGE-specific and default
894 ;; ones. Otherwise, accept headers from any loaded
897 org-babel-header-arg-names
900 (let ((v (intern (format "org-babel-header-args:%s" l
))))
901 (and (boundp v
) (mapcar #'car
(symbol-value v
)))))
902 (if language
(list language
)
903 (mapcar #'car org-babel-load-languages
))))))
904 (dolist (header headers
)
905 (let ((h (symbol-name (car header
)))
906 (p (or (org-element-property :post-affiliated datum
)
907 (org-element-property :begin datum
))))
909 ((not (string-prefix-p ":" h
))
912 (format "Missing colon in header argument \"%s\"" h
))
914 ((assoc-string (substring h
1) allowed
))
915 (t (push (list p
(format "Unknown header argument \"%s\"" h
))
917 (org-element-map ast
'(babel-call inline-babel-call inline-src-block keyword
918 node-property src-block
)
920 (pcase (org-element-type datum
)
921 ((or `babel-call
`inline-babel-call
)
925 (cl-mapcan #'org-babel-parse-header-arguments
927 (org-element-property :inside-header datum
)
928 (org-element-property :end-header datum
)))))
932 (org-element-property :language datum
)
933 (org-babel-parse-header-arguments
934 (org-element-property :parameters datum
))))
936 (when (string= (org-element-property :key datum
) "PROPERTY")
937 (let ((value (org-element-property :value datum
)))
938 (when (string-match "\\`header-args\\(?::\\(\\S-+\\)\\)?\\+? *"
942 (match-string 1 value
)
943 (org-babel-parse-header-arguments
944 (substring value
(match-end 0))))))))
946 (let ((key (org-element-property :key datum
)))
947 (when (let ((case-fold-search t
))
948 (string-match "\\`HEADER-ARGS\\(?::\\(\\S-+\\)\\)?\\+?"
953 (org-babel-parse-header-arguments
954 (org-element-property :value datum
))))))
958 (org-element-property :language datum
)
959 (cl-mapcan #'org-babel-parse-header-arguments
960 (cons (org-element-property :parameters datum
)
961 (org-element-property :header datum
))))))))
964 (defun org-lint-wrong-header-value (ast)
967 '(babel-call inline-babel-call inline-src-block src-block
)
969 (let* ((type (org-element-type datum
))
970 (language (org-element-property :language datum
))
971 (allowed-header-values
972 (append (and language
973 (let ((v (intern (concat "org-babel-header-args:"
975 (and (boundp v
) (symbol-value v
))))
976 org-babel-common-header-args-w-values
))
978 (org-babel-parse-header-arguments
984 (cons (org-element-property :parameters datum
)
985 (org-element-property :header datum
))
988 (or (org-element-property :parameters datum
) ""))
991 (org-element-property :inside-header datum
)
993 (org-element-property :end-header datum
))))))))
994 (dolist (header datum-header-values
)
995 (let ((allowed-values
996 (cdr (assoc-string (substring (symbol-name (car header
)) 1)
997 allowed-header-values
))))
998 (unless (memq allowed-values
'(:any nil
))
999 (let ((values (cdr header
))
1001 (dolist (v (if (stringp values
) (org-split-string values
)
1003 (let ((valid-value nil
))
1005 (dolist (group allowed-values
)
1008 (if (stringp v
) #'assoc-string
#'assoc
)
1010 (when (memq :any group
)
1011 (setf valid-value t
)
1012 (push (cons group v
) groups-alist
)))
1013 ((assq group groups-alist
)
1016 (or (org-element-property :post-affiliated datum
)
1017 (org-element-property :begin datum
))
1019 "Forbidden combination in header \"%s\": %s, %s"
1021 (cdr (assq group groups-alist
))
1025 (t (push (cons group v
) groups-alist
)
1026 (setf valid-value t
))))
1030 (or (org-element-property :post-affiliated datum
)
1031 (org-element-property :begin datum
))
1032 (format "Unknown value \"%s\" for header \"%s\""
1038 (defun org-lint-empty-headline-with-tags (ast)
1039 (org-element-map ast
'(headline inlinetask
)
1041 (let ((title (org-element-property :raw-value h
)))
1042 (and (string-match-p "\\`:[[:alnum:]_@#%:]+:\\'" title
)
1043 (list (org-element-property :begin h
)
1044 (format "Headline containing only tags is ambiguous: %S"
1050 (defvar org-lint--report-mode-map
1051 (let ((map (make-sparse-keymap)))
1052 (set-keymap-parent map tabulated-list-mode-map
)
1053 (define-key map
(kbd "RET") 'org-lint--jump-to-source
)
1054 (define-key map
(kbd "TAB") 'org-lint--show-source
)
1055 (define-key map
(kbd "C-j") 'org-lint--show-source
)
1056 (define-key map
(kbd "h") 'org-lint--hide-checker
)
1057 (define-key map
(kbd "i") 'org-lint--ignore-checker
)
1059 "Local keymap for `org-lint--report-mode' buffers.")
1061 (define-derived-mode org-lint--report-mode tabulated-list-mode
"OrgLint"
1062 "Major mode used to display reports emitted during linting.
1063 \\{org-lint--report-mode-map}"
1064 (setf tabulated-list-format
1067 (< (string-to-number (aref (cadr a
) 0))
1068 (string-to-number (aref (cadr b
) 0))))
1072 (tabulated-list-init-header))
1074 (defun org-lint--generate-reports (buffer checkers
)
1075 "Generate linting report for BUFFER.
1077 CHECKERS is the list of checkers used.
1079 Return an alist (ID [LINE TRUST DESCRIPTION CHECKER]), suitable
1080 for `tabulated-list-printer'."
1081 (with-current-buffer buffer
1083 (goto-char (point-min))
1084 (let ((ast (org-element-parse-buffer))
1088 ;; Insert unique ID for each report. Replace buffer positions
1089 ;; with line numbers.
1097 (goto-char (car report
))
1099 (prog1 (number-to-string
1101 (count-lines last-pos
(point))))
1102 (setf last-pos
(point))))
1104 ;; Insert trust level in generated reports. Also sort them
1105 ;; by buffer position in order to optimize lines computation.
1108 (let ((trust (symbol-name (org-lint-checker-trust c
))))
1111 (list (car report
) trust
(nth 1 report
) c
))
1114 (intern (format "org-lint-%s"
1115 (org-lint-checker-name c
)))
1118 #'car-less-than-car
))))))
1120 (defvar-local org-lint--source-buffer nil
1121 "Source buffer associated to current report buffer.")
1123 (defvar-local org-lint--local-checkers nil
1124 "List of checkers used to build current report.")
1126 (defun org-lint--refresh-reports ()
1127 (setq tabulated-list-entries
1128 (org-lint--generate-reports org-lint--source-buffer
1129 org-lint--local-checkers
))
1130 (tabulated-list-print))
1132 (defun org-lint--current-line ()
1133 "Return current report line, as a number."
1134 (string-to-number (aref (tabulated-list-get-entry) 0)))
1136 (defun org-lint--current-checker (&optional entry
)
1137 "Return current report checker.
1138 When optional argument ENTRY is non-nil, use this entry instead
1140 (aref (if entry
(nth 1 entry
) (tabulated-list-get-entry)) 3))
1142 (defun org-lint--display-reports (source checkers
)
1143 "Display linting reports for buffer SOURCE.
1144 CHECKERS is the list of checkers used."
1145 (let ((buffer (get-buffer-create "*Org Lint*")))
1146 (with-current-buffer buffer
1147 (org-lint--report-mode)
1148 (setf org-lint--source-buffer source
)
1149 (setf org-lint--local-checkers checkers
)
1150 (org-lint--refresh-reports)
1151 (tabulated-list-print)
1152 (add-hook 'tabulated-list-revert-hook
#'org-lint--refresh-reports nil t
))
1153 (pop-to-buffer buffer
)))
1155 (defun org-lint--jump-to-source ()
1156 "Move to source line that generated the report at point."
1158 (let ((l (org-lint--current-line)))
1159 (switch-to-buffer-other-window org-lint--source-buffer
)
1161 (org-show-set-visibility 'local
)
1164 (defun org-lint--show-source ()
1165 "Show source line that generated the report at point."
1167 (let ((buffer (current-buffer)))
1168 (org-lint--jump-to-source)
1169 (switch-to-buffer-other-window buffer
)))
1171 (defun org-lint--hide-checker ()
1172 "Hide all reports from checker that generated the report at point."
1174 (let ((c (org-lint--current-checker)))
1175 (setf tabulated-list-entries
1176 (cl-remove-if (lambda (e) (equal c
(org-lint--current-checker e
)))
1177 tabulated-list-entries
))
1178 (tabulated-list-print)))
1180 (defun org-lint--ignore-checker ()
1181 "Ignore all reports from checker that generated the report at point.
1182 Checker will also be ignored in all subsequent reports."
1184 (setf org-lint--local-checkers
1185 (remove (org-lint--current-checker) org-lint--local-checkers
))
1186 (org-lint--hide-checker))
1192 (defun org-lint (&optional arg
)
1193 "Check current Org buffer for syntax mistakes.
1195 By default, run all checkers. With a `\\[universal-argument]' prefix ARG, \
1197 category of checkers only. With a `\\[universal-argument] \
1198 \\[universal-argument]' prefix, run one precise
1199 checker by its name.
1201 ARG can also be a list of checker names, as symbols, to run."
1203 (unless (derived-mode-p 'org-mode
) (user-error "Not in an Org buffer"))
1204 (when (called-interactively-p 'any
)
1205 (message "Org linting process starting..."))
1208 (`nil org-lint--checkers
)
1212 "Checker category: "
1213 (mapcar #'org-lint-checker-categories org-lint--checkers
)
1217 (assoc-string (org-lint-checker-categories c
) category
))
1218 org-lint--checkers
)))
1221 (let ((name (completing-read
1223 (mapcar #'org-lint-checker-name org-lint--checkers
)
1226 (dolist (c org-lint--checkers
)
1227 (when (string= (org-lint-checker-name c
) name
)
1228 (throw 'exit c
)))))))
1230 (cl-remove-if-not (lambda (c) (memq (org-lint-checker-name c
) arg
))
1231 org-lint--checkers
))
1232 (_ (user-error "Invalid argument `%S' for `org-lint'" arg
)))))
1233 (if (not (called-interactively-p 'any
))
1234 (org-lint--generate-reports (current-buffer) checkers
)
1235 (org-lint--display-reports (current-buffer) checkers
)
1236 (message "Org linting process completed"))))
1240 ;;; org-lint.el ends here