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 ;; - missing definition for footnote references
91 ;; - missing reference for footnote definitions
92 ;; - non-footnote definitions in footnote section
93 ;; - probable invalid keywords
95 ;; - misplaced planning info line
96 ;; - incomplete drawers
97 ;; - indented diary-sexps
98 ;; - obsolete QUOTE section
99 ;; - obsolete "file+application" link
105 (require 'org-element
)
113 (cl-defstruct (org-lint-checker (:copier nil
))
114 (name 'missing-checker-name
)
116 (categories '(default))
117 (trust 'high
)) ; `low' or `high'
119 (defun org-lint-missing-checker-name (_)
121 "`A checker has no `:name' property. Please verify `org-lint--checkers'"))
123 (defconst org-lint--checkers
125 (make-org-lint-checker
126 :name
'duplicate-custom-id
127 :description
"Report duplicates CUSTOM_ID properties"
129 (make-org-lint-checker
130 :name
'duplicate-name
131 :description
"Report duplicate NAME values"
132 :categories
'(babel link
))
133 (make-org-lint-checker
134 :name
'duplicate-target
135 :description
"Report duplicate targets"
137 (make-org-lint-checker
138 :name
'duplicate-footnote-definition
139 :description
"Report duplicate footnote definitions"
140 :categories
'(footnote))
141 (make-org-lint-checker
142 :name
'orphaned-affiliated-keywords
143 :description
"Report orphaned affiliated keywords"
145 (make-org-lint-checker
146 :name
'obsolete-affiliated-keywords
147 :description
"Report obsolete affiliated keywords"
148 :categories
'(obsolete))
149 (make-org-lint-checker
150 :name
'deprecated-export-blocks
151 :description
"Report deprecated export block syntax"
152 :categories
'(obsolete export
)
154 (make-org-lint-checker
155 :name
'deprecated-header-syntax
156 :description
"Report deprecated Babel header syntax"
157 :categories
'(obsolete babel
)
159 (make-org-lint-checker
160 :name
'missing-language-in-src-block
161 :description
"Report missing language in src blocks"
162 :categories
'(babel))
163 (make-org-lint-checker
164 :name
'missing-backend-in-export-block
165 :description
"Report missing back-end in export blocks"
166 :categories
'(export))
167 (make-org-lint-checker
168 :name
'invalid-babel-call-block
169 :description
"Report invalid Babel call blocks"
170 :categories
'(babel))
171 (make-org-lint-checker
173 :description
"Report NAME values with a colon"
174 :categories
'(babel))
175 (make-org-lint-checker
176 :name
'wrong-header-argument
177 :description
"Report wrong babel headers"
178 :categories
'(babel))
179 (make-org-lint-checker
180 :name
'wrong-header-value
181 :description
"Report invalid value in babel headers"
184 (make-org-lint-checker
185 :name
'deprecated-category-setup
186 :description
"Report misuse of CATEGORY keyword"
187 :categories
'(obsolete))
188 (make-org-lint-checker
189 :name
'invalid-coderef-link
190 :description
"Report \"coderef\" links with unknown destination"
192 (make-org-lint-checker
193 :name
'invalid-custom-id-link
194 :description
"Report \"custom-id\" links with unknown destination"
196 (make-org-lint-checker
197 :name
'invalid-fuzzy-link
198 :description
"Report \"fuzzy\" links with unknown destination"
200 (make-org-lint-checker
201 :name
'invalid-id-link
202 :description
"Report \"id\" links with unknown destination"
204 (make-org-lint-checker
205 :name
'link-to-local-file
206 :description
"Report links to non-existent local files"
209 (make-org-lint-checker
210 :name
'non-existent-setupfile-parameter
211 :description
"Report SETUPFILE keywords with non-existent file parameter"
213 (make-org-lint-checker
214 :name
'wrong-include-link-parameter
215 :description
"Report INCLUDE keywords with misleading link parameter"
216 :categories
'(export)
218 (make-org-lint-checker
219 :name
'obsolete-include-markup
220 :description
"Report obsolete markup in INCLUDE keyword"
221 :categories
'(obsolete export
)
223 (make-org-lint-checker
224 :name
'unknown-options-item
225 :description
"Report unknown items in OPTIONS keyword"
226 :categories
'(export)
228 (make-org-lint-checker
229 :name
'invalid-macro-argument-and-template
230 :description
"Report spurious macro arguments or invalid macro templates"
231 :categories
'(export)
233 (make-org-lint-checker
234 :name
'special-property-in-properties-drawer
235 :description
"Report special properties in properties drawers"
236 :categories
'(properties))
237 (make-org-lint-checker
238 :name
'obsolete-properties-drawer
239 :description
"Report obsolete syntax for properties drawers"
240 :categories
'(obsolete properties
))
241 (make-org-lint-checker
242 :name
'undefined-footnote-reference
243 :description
"Report missing definition for footnote references"
244 :categories
'(footnote))
245 (make-org-lint-checker
246 :name
'unreferenced-footnote-definition
247 :description
"Report missing reference for footnote definitions"
248 :categories
'(footnote))
249 (make-org-lint-checker
250 :name
'extraneous-element-in-footnote-section
251 :description
"Report non-footnote definitions in footnote section"
252 :categories
'(footnote))
253 (make-org-lint-checker
254 :name
'invalid-keyword-syntax
255 :description
"Report probable invalid keywords"
257 (make-org-lint-checker
259 :description
"Report invalid blocks"
261 (make-org-lint-checker
262 :name
'misplaced-planning-info
263 :description
"Report misplaced planning info line"
265 (make-org-lint-checker
266 :name
'incomplete-drawer
267 :description
"Report probable incomplete drawers"
269 (make-org-lint-checker
270 :name
'indented-diary-sexp
271 :description
"Report probable indented diary-sexps"
273 (make-org-lint-checker
275 :description
"Report obsolete QUOTE section"
276 :categories
'(obsolete)
278 (make-org-lint-checker
279 :name
'file-application
280 :description
"Report obsolete \"file+application\" link"
281 :categories
'(link obsolete
)))
282 "List of all available checkers.")
284 (defun org-lint--collect-duplicates
285 (ast type extract-key extract-position build-message
)
286 "Helper function to collect duplicates in parse tree AST.
288 EXTRACT-KEY is a function extracting key. It is called with
289 a single argument: the element or object. Comparison is done
292 EXTRACT-POSITION is a function returning position for the report.
293 It is called with two arguments, the object or element, and the
296 BUILD-MESSAGE is a function creating the report message. It is
297 called with one argument, the key used for comparison."
302 (lambda (position value
)
303 (push (list position
(funcall build-message value
)) reports
))))
304 (org-element-map ast type
306 (let ((key (funcall extract-key datum
)))
309 ((assoc key keys
) (cl-pushnew (assoc key keys
) originals
)
310 (funcall make-report
(funcall extract-position datum key
) key
))
311 (t (push (cons key
(funcall extract-position datum key
)) keys
))))))
312 (dolist (e originals reports
) (funcall make-report
(cdr e
) (car e
)))))
314 (defun org-lint-duplicate-custom-id (ast)
315 (org-lint--collect-duplicates
319 (and (eq (compare-strings "CUSTOM_ID" nil nil
320 (org-element-property :key property
) nil nil
323 (org-element-property :value property
)))
324 (lambda (property _
) (org-element-property :begin property
))
325 (lambda (key) (format "Duplicate CUSTOM_ID property \"%s\"" key
))))
327 (defun org-lint-duplicate-name (ast)
328 (org-lint--collect-duplicates
330 org-element-all-elements
331 (lambda (datum) (org-element-property :name datum
))
333 (goto-char (org-element-property :begin datum
))
335 (format "^[ \t]*#\\+[A-Za-z]+: +%s *$" (regexp-quote name
)))
337 (lambda (key) (format "Duplicate NAME \"%s\"" key
))))
339 (defun org-lint-duplicate-target (ast)
340 (org-lint--collect-duplicates
343 (lambda (target) (org-split-string (org-element-property :value target
)))
344 (lambda (target _
) (org-element-property :begin target
))
346 (format "Duplicate target <<%s>>" (mapconcat #'identity key
" ")))))
348 (defun org-lint-duplicate-footnote-definition (ast)
349 (org-lint--collect-duplicates
352 (lambda (definition) (org-element-property :label definition
))
353 (lambda (definition _
) (org-element-property :post-affiliated definition
))
354 (lambda (key) (format "Duplicate footnote definition \"%s\"" key
))))
356 (defun org-lint-orphaned-affiliated-keywords (ast)
357 ;; Ignore orphan RESULTS keywords, which could be generated from
358 ;; a source block returning no value.
359 (let ((keywords (cl-set-difference org-element-affiliated-keywords
360 '("RESULT" "RESULTS")
362 (org-element-map ast
'keyword
364 (let ((key (org-element-property :key k
)))
365 (and (or (let ((case-fold-search t
))
366 (string-match-p "\\`ATTR_[-_A-Za-z0-9]+\\'" key
))
367 (member key keywords
))
368 (list (org-element-property :post-affiliated k
)
369 (format "Orphaned affiliated keyword: \"%s\"" key
))))))))
371 (defun org-lint-obsolete-affiliated-keywords (_)
372 (let ((regexp (format "^[ \t]*#\\+%s:"
373 (regexp-opt '("DATA" "LABEL" "RESNAME" "SOURCE"
374 "SRCNAME" "TBLNAME" "RESULT" "HEADERS")
377 (while (re-search-forward regexp nil t
)
378 (let ((key (upcase (match-string-no-properties 1))))
380 (org-element-property :post-affiliated
(org-element-at-point)))
382 (list (line-beginning-position)
384 "Obsolete affiliated keyword: \"%s\". Use \"%s\" instead"
393 (defun org-lint-deprecated-export-blocks (ast)
394 (let ((deprecated '("ASCII" "BEAMER" "HTML" "LATEX" "MAN" "MARKDOWN" "MD"
395 "ODT" "ORG" "TEXINFO")))
396 (org-element-map ast
'special-block
398 (let ((type (org-element-property :type b
)))
399 (when (member-ignore-case type deprecated
)
401 (org-element-property :post-affiliated b
)
403 "Deprecated syntax for export block. Use \"BEGIN_EXPORT %s\" \
407 (defun org-lint-deprecated-header-syntax (ast)
408 (let* ((deprecated-babel-properties
409 (mapcar (lambda (arg) (symbol-name (car arg
)))
410 org-babel-common-header-args-w-values
))
412 (format "\\`%s[ \t]" (regexp-opt deprecated-babel-properties t
))))
413 (org-element-map ast
'(keyword node-property
)
415 (let ((key (org-element-property :key datum
)))
416 (pcase (org-element-type datum
)
418 (let ((value (org-element-property :value datum
)))
419 (and (string= key
"PROPERTY")
420 (string-match deprecated-re value
)
421 (list (org-element-property :begin datum
)
422 (format "Deprecated syntax for \"%s\". \
423 Use header-args instead"
424 (match-string-no-properties 1 value
))))))
426 (and (member-ignore-case key deprecated-babel-properties
)
428 (org-element-property :begin datum
)
429 (format "Deprecated syntax for \"%s\". \
430 Use :header-args: instead"
433 (defun org-lint-missing-language-in-src-block (ast)
434 (org-element-map ast
'src-block
436 (unless (org-element-property :language b
)
437 (list (org-element-property :post-affiliated b
)
438 "Missing language in source block")))))
440 (defun org-lint-missing-backend-in-export-block (ast)
441 (org-element-map ast
'export-block
443 (unless (org-element-property :type b
)
444 (list (org-element-property :post-affiliated b
)
445 "Missing back-end in export block")))))
447 (defun org-lint-invalid-babel-call-block (ast)
448 (org-element-map ast
'babel-call
451 ((not (org-element-property :call b
))
452 (list (org-element-property :post-affiliated b
)
453 "Invalid syntax in babel call block"))
454 ((let ((h (org-element-property :end-header b
)))
455 (and h
(string-match-p "\\`\\[.*\\]\\'" h
)))
457 (org-element-property :post-affiliated b
)
458 "Babel call's end header must not be wrapped within brackets"))))))
460 (defun org-lint-deprecated-category-setup (ast)
461 (org-element-map ast
'keyword
465 ((not (string= (org-element-property :key k
) "CATEGORY")) nil
)
467 (list (org-element-property :post-affiliated k
)
468 "Spurious CATEGORY keyword. Set :CATEGORY: property instead"))
469 (t (setf category-flag t
) nil
))))))
471 (defun org-lint-invalid-coderef-link (ast)
472 (let ((info (list :parse-tree ast
)))
473 (org-element-map ast
'link
475 (let ((ref (org-element-property :path link
)))
476 (and (equal (org-element-property :type link
) "coderef")
477 (not (ignore-errors (org-export-resolve-coderef ref info
)))
478 (list (org-element-property :begin link
)
479 (format "Unknown coderef \"%s\"" ref
))))))))
481 (defun org-lint-invalid-custom-id-link (ast)
482 (let ((info (list :parse-tree ast
)))
483 (org-element-map ast
'link
485 (and (equal (org-element-property :type link
) "custom-id")
486 (not (ignore-errors (org-export-resolve-id-link link info
)))
487 (list (org-element-property :begin link
)
488 (format "Unknown custom ID \"%s\""
489 (org-element-property :path link
))))))))
491 (defun org-lint-invalid-fuzzy-link (ast)
492 (let ((info (list :parse-tree ast
)))
493 (org-element-map ast
'link
495 (and (equal (org-element-property :type link
) "fuzzy")
496 (not (ignore-errors (org-export-resolve-fuzzy-link link info
)))
497 (list (org-element-property :begin link
)
498 (format "Unknown fuzzy location \"%s\""
499 (let ((path (org-element-property :path link
)))
500 (if (string-prefix-p "*" path
)
504 (defun org-lint-invalid-id-link (ast)
505 (org-element-map ast
'link
507 (let ((id (org-element-property :path link
)))
508 (and (equal (org-element-property :type link
) "id")
509 (not (org-id-find id
))
510 (list (org-element-property :begin link
)
511 (format "Unknown ID \"%s\"" id
)))))))
513 (defun org-lint-special-property-in-properties-drawer (ast)
514 (org-element-map ast
'node-property
516 (let ((key (org-element-property :key p
)))
517 (and (member-ignore-case key org-special-properties
)
518 (list (org-element-property :begin p
)
520 "Special property \"%s\" found in a properties drawer"
523 (defun org-lint-obsolete-properties-drawer (ast)
524 (org-element-map ast
'drawer
526 (when (equal (org-element-property :drawer-name d
) "PROPERTIES")
527 (let ((section (org-element-lineage d
'(section))))
528 (unless (org-element-map section
'property-drawer
#'identity nil t
)
529 (list (org-element-property :post-affiliated d
)
531 (goto-char (org-element-property :post-affiliated d
))
533 (or (org-at-heading-p) (org-at-planning-p)))
534 "Incorrect contents for PROPERTIES drawer"
535 "Incorrect location for PROPERTIES drawer"))))))))
537 (defun org-lint-link-to-local-file (ast)
538 (org-element-map ast
'link
540 (when (equal (org-element-property :type l
) "file")
541 (let ((file (org-link-unescape (org-element-property :path l
))))
542 (and (not (file-remote-p file
))
543 (not (file-exists-p file
))
544 (list (org-element-property :begin l
)
545 (format (if (org-element-lineage l
'(link))
546 "Link to non-existent image file \"%s\"\
548 "Link to non-existent local file \"%s\"")
551 (defun org-lint-non-existent-setupfile-parameter (ast)
552 (org-element-map ast
'keyword
554 (when (equal (org-element-property :key k
) "SETUPFILE")
555 (let ((file (org-unbracket-string
557 (org-element-property :value k
))))
558 (and (not (file-remote-p file
))
559 (not (file-exists-p file
))
560 (list (org-element-property :begin k
)
561 (format "Non-existent setup file \"%s\"" file
))))))))
563 (defun org-lint-wrong-include-link-parameter (ast)
564 (org-element-map ast
'keyword
566 (when (equal (org-element-property :key k
) "INCLUDE")
567 (let* ((value (org-element-property :value k
))
569 (and (string-match "^\\(\".+\"\\|\\S-+\\)[ \t]*" value
)
571 (org-unbracket-string "\"" "\"" (match-string 1 value
))))))
573 (list (org-element-property :post-affiliated k
)
574 "Missing location argument in INCLUDE keyword")
575 (let* ((file (org-string-nw-p
576 (if (string-match "::\\(.*\\)\\'" path
)
577 (substring path
0 (match-beginning 0))
579 (search (and (not (equal file path
))
580 (org-string-nw-p (match-string 1 path
)))))
582 (not (file-remote-p file
))
583 (not (file-exists-p file
)))
584 (list (org-element-property :post-affiliated k
)
585 "Non-existent file argument in INCLUDE keyword")
586 (let* ((visiting (if file
(find-buffer-visiting file
)
588 (buffer (or visiting
(find-file-noselect file
))))
590 (with-current-buffer buffer
594 (let ((org-link-search-inhibit-query t
))
595 (org-link-search search nil t
)))))
596 (list (org-element-property :post-affiliated k
)
598 "Invalid search part \"%s\" in INCLUDE keyword"
600 (unless visiting
(kill-buffer buffer
))))))))))))
602 (defun org-lint-obsolete-include-markup (ast)
603 (let ((regexp (format "\\`\\(?:\".+\"\\|\\S-+\\)[ \t]+%s"
605 '("ASCII" "BEAMER" "HTML" "LATEX" "MAN" "MARKDOWN" "MD"
606 "ODT" "ORG" "TEXINFO")
608 (org-element-map ast
'keyword
610 (when (equal (org-element-property :key k
) "INCLUDE")
611 (let ((case-fold-search t
)
612 (value (org-element-property :value k
)))
613 (when (string-match regexp value
)
614 (let ((markup (match-string-no-properties 1 value
)))
615 (list (org-element-property :post-affiliated k
)
616 (format "Obsolete markup \"%s\" in INCLUDE keyword. \
617 Use \"export %s\" instead"
621 (defun org-lint-unknown-options-item (ast)
622 (let ((allowed (delq nil
624 (mapcar (lambda (o) (nth 2 o
)) org-export-options-alist
)
627 (mapcar (lambda (o) (nth 2 o
))
628 (org-export-backend-options b
)))
629 org-export-registered-backends
))))
631 (org-element-map ast
'keyword
633 (when (string= (org-element-property :key k
) "OPTIONS")
634 (let ((value (org-element-property :value k
))
636 (while (string-match "\\(.+?\\):\\((.*?)\\|\\S-*\\)[ \t]*"
639 (setf start
(match-end 0))
640 (let ((item (match-string 1 value
)))
641 (unless (member item allowed
)
642 (push (list (org-element-property :post-affiliated k
)
643 (format "Unknown OPTIONS item \"%s\"" item
))
647 (defun org-lint-invalid-macro-argument-and-template (ast)
648 (let ((extract-placeholders
652 (while (string-match "\\$\\([1-9][0-9]*\\)" template start
)
653 (setf start
(match-end 0))
654 (push (string-to-number (match-string 1 template
)) args
))
655 (sort (org-uniquify args
) #'<))))
657 ;; Check arguments for macro templates.
658 (org-element-map ast
'keyword
660 (when (string= (org-element-property :key k
) "MACRO")
661 (let* ((value (org-element-property :value k
))
662 (name (and (string-match "^\\S-+" value
)
663 (match-string 0 value
)))
665 (org-trim (substring value
(match-end 0))))))
668 (push (list (org-element-property :post-affiliated k
)
669 "Missing name in MACRO keyword")
671 ((not (org-string-nw-p template
))
672 (push (list (org-element-property :post-affiliated k
)
673 "Missing template in macro \"%s\"" name
)
676 (unless (let ((args (funcall extract-placeholders template
)))
677 (equal (number-sequence 1 (or (org-last args
) 0)) args
))
678 (push (list (org-element-property :post-affiliated k
)
679 (format "Unused placeholders in macro \"%s\""
682 ;; Check arguments for macros.
683 (org-macro-initialize-templates)
684 (let ((templates (append
685 (mapcar (lambda (m) (cons m
"$1"))
686 '("author" "date" "email" "title" "results"))
687 org-macro-templates
)))
688 (org-element-map ast
'macro
690 (let* ((name (org-element-property :key macro
))
691 (template (cdr (assoc-string name templates t
))))
693 (push (list (org-element-property :begin macro
)
694 (format "Undefined macro \"%s\"" name
))
696 (let ((arg-numbers (funcall extract-placeholders template
)))
699 (nthcdr (apply #'max arg-numbers
)
700 (org-element-property :args macro
))))
703 (list (org-element-property :begin macro
)
704 (format "Unused argument%s in macro \"%s\": %s"
705 (if (> (length spurious-args
) 1) "s" "")
707 (mapconcat (lambda (a) (format "\"%s\"" a
))
713 (defun org-lint-undefined-footnote-reference (ast)
714 (let ((definitions (org-element-map ast
'footnote-definition
715 (lambda (f) (org-element-property :label f
)))))
716 (org-element-map ast
'footnote-reference
718 (let ((label (org-element-property :label f
)))
720 (not (member label definitions
))
721 (list (org-element-property :begin f
)
722 (format "Missing definition for footnote [%s]"
725 (defun org-lint-unreferenced-footnote-definition (ast)
726 (let ((references (org-element-map ast
'footnote-reference
727 (lambda (f) (org-element-property :label f
)))))
728 (org-element-map ast
'footnote-definition
730 (let ((label (org-element-property :label f
)))
732 (not (member label references
))
733 (list (org-element-property :post-affiliated f
)
734 (format "No reference for footnote definition [%s]"
737 (defun org-lint-colon-in-name (ast)
738 (org-element-map ast org-element-all-elements
740 (let ((name (org-element-property :name e
)))
742 (string-match-p ":" name
)
744 (goto-char (org-element-property :begin e
))
746 (format "^[ \t]*#\\+\\w+: +%s *$" (regexp-quote name
)))
749 "Name \"%s\" contains a colon; Babel cannot use it as input"
752 (defun org-lint-misplaced-planning-info (_)
753 (let ((case-fold-search t
)
755 (while (re-search-forward org-planning-line-re nil t
)
756 (unless (memq (org-element-type (org-element-at-point))
757 '(comment-block example-block export-block planning
758 src-block verse-block
))
759 (push (list (line-beginning-position) "Misplaced planning info line")
763 (defun org-lint-incomplete-drawer (_)
765 (while (re-search-forward org-drawer-regexp nil t
)
766 (let ((name (org-trim (match-string-no-properties 0)))
767 (element (org-element-at-point)))
768 (pcase (org-element-type element
)
769 ((or `drawer
`property-drawer
)
770 (goto-char (org-element-property :end element
))
772 ((or `comment-block
`example-block
`export-block
`src-block
776 (push (list (line-beginning-position)
777 (format "Possible incomplete drawer \"%s\"" name
))
781 (defun org-lint-indented-diary-sexp (_)
783 (while (re-search-forward "^[ \t]+%%(" nil t
)
784 (unless (memq (org-element-type (org-element-at-point))
785 '(comment-block diary-sexp example-block export-block
786 src-block verse-block
))
787 (push (list (line-beginning-position) "Possible indented diary-sexp")
791 (defun org-lint-invalid-block (_)
792 (let ((case-fold-search t
)
793 (regexp "^[ \t]*#\\+\\(BEGIN\\|END\\)\\(?::\\|_[^[:space:]]*\\)?[ \t]*")
795 (while (re-search-forward regexp nil t
)
796 (let ((name (org-trim (buffer-substring-no-properties
797 (line-beginning-position) (line-end-position)))))
799 ((and (string-prefix-p "END" (match-string 1) t
)
801 (push (list (line-beginning-position)
802 (format "Invalid block closing line \"%s\"" name
))
804 ((not (memq (org-element-type (org-element-at-point))
805 '(center-block comment-block dynamic-block example-block
806 export-block quote-block special-block
807 src-block verse-block
)))
808 (push (list (line-beginning-position)
809 (format "Possible incomplete block \"%s\""
814 (defun org-lint-invalid-keyword-syntax (_)
815 (let ((regexp "^[ \t]*#\\+\\([^[:space:]:]*\\)\\(?: \\|$\\)")
817 (format "[ \t]*#\\+%s\\(\\[.*\\]\\)?:\\(?: \\|$\\)"
818 (regexp-opt org-element-dual-keywords
)))
820 (while (re-search-forward regexp nil t
)
821 (let ((name (match-string-no-properties 1)))
822 (unless (or (string-prefix-p "BEGIN" name t
)
823 (string-prefix-p "END" name t
)
826 (let ((case-fold-search t
)) (looking-at exception-re
))))
827 (push (list (match-beginning 0)
828 (format "Possible missing colon in keyword \"%s\"" name
))
832 (defun org-lint-extraneous-element-in-footnote-section (ast)
833 (org-element-map ast
'headline
835 (and (org-element-property :footnote-section-p h
)
836 (org-element-map (org-element-contents h
)
839 (memq e
'(comment comment-block footnote-definition
840 property-drawer section
)))
841 org-element-all-elements
)
843 (not (and (eq (org-element-type e
) 'headline
)
844 (org-element-property :commentedp e
))))
845 nil t
'(footnote-definition property-drawer
))
846 (list (org-element-property :begin h
)
847 "Extraneous elements in footnote section are not exported")))))
849 (defun org-lint-quote-section (ast)
850 (org-element-map ast
'(headline inlinetask
)
852 (let ((title (org-element-property :raw-value h
)))
853 (and (or (string-prefix-p "QUOTE " title
)
854 (string-prefix-p (concat org-comment-string
" QUOTE ") title
))
855 (list (org-element-property :begin h
)
856 "Deprecated QUOTE section"))))))
858 (defun org-lint-file-application (ast)
859 (org-element-map ast
'link
861 (let ((app (org-element-property :application l
)))
863 (list (org-element-property :begin l
)
864 (format "Deprecated \"file+%s\" link type" app
)))))))
866 (defun org-lint-wrong-header-argument (ast)
869 (lambda (datum language headers
)
871 ;; If LANGUAGE is specified, restrict allowed
872 ;; headers to both LANGUAGE-specific and default
873 ;; ones. Otherwise, accept headers from any loaded
876 org-babel-header-arg-names
879 (let ((v (intern (format "org-babel-header-args:%s" l
))))
880 (and (boundp v
) (mapcar #'car
(symbol-value v
)))))
881 (if language
(list language
)
882 (mapcar #'car org-babel-load-languages
))))))
883 (dolist (header headers
)
884 (let ((h (symbol-name (car header
)))
885 (p (or (org-element-property :post-affiliated datum
)
886 (org-element-property :begin datum
))))
888 ((not (string-prefix-p ":" h
))
891 (format "Missing colon in header argument \"%s\"" h
))
893 ((assoc-string (substring h
1) allowed
))
894 (t (push (list p
(format "Unknown header argument \"%s\"" h
))
896 (org-element-map ast
'(babel-call inline-babel-call inline-src-block keyword
897 node-property src-block
)
899 (pcase (org-element-type datum
)
900 ((or `babel-call
`inline-babel-call
)
904 (cl-mapcan #'org-babel-parse-header-arguments
906 (org-element-property :inside-header datum
)
907 (org-element-property :end-header datum
)))))
911 (org-element-property :language datum
)
912 (org-babel-parse-header-arguments
913 (org-element-property :parameters datum
))))
915 (when (string= (org-element-property :key datum
) "PROPERTY")
916 (let ((value (org-element-property :value datum
)))
917 (when (string-match "\\`header-args\\(?::\\(\\S-+\\)\\)?\\+? *"
921 (match-string 1 value
)
922 (org-babel-parse-header-arguments
923 (substring value
(match-end 0))))))))
925 (let ((key (org-element-property :key datum
)))
926 (when (let ((case-fold-search t
))
927 (string-match "\\`HEADER-ARGS\\(?::\\(\\S-+\\)\\)?\\+?"
932 (org-babel-parse-header-arguments
933 (org-element-property :value datum
))))))
937 (org-element-property :language datum
)
938 (cl-mapcan #'org-babel-parse-header-arguments
939 (cons (org-element-property :parameters datum
)
940 (org-element-property :header datum
))))))))
943 (defun org-lint-wrong-header-value (ast)
946 '(babel-call inline-babel-call inline-src-block src-block
)
948 (let* ((type (org-element-type datum
))
949 (language (org-element-property :language datum
))
950 (allowed-header-values
951 (append (and language
952 (let ((v (intern (concat "org-babel-header-args:"
954 (and (boundp v
) (symbol-value v
))))
955 org-babel-common-header-args-w-values
))
957 (org-babel-parse-header-arguments
963 (cons (org-element-property :parameters datum
)
964 (org-element-property :header datum
))
967 (or (org-element-property :parameters datum
) ""))
970 (org-element-property :inside-header datum
)
972 (org-element-property :end-header datum
))))))))
973 (dolist (header datum-header-values
)
974 (let ((allowed-values
975 (cdr (assoc-string (substring (symbol-name (car header
)) 1)
976 allowed-header-values
))))
977 (unless (memq allowed-values
'(:any nil
))
978 (let ((values (cdr header
))
980 (dolist (v (if (stringp values
) (org-split-string values
)
982 (let ((valid-value nil
))
984 (dolist (group allowed-values
)
987 (if (stringp v
) #'assoc-string
#'assoc
)
989 (when (memq :any group
)
991 (push (cons group v
) groups-alist
)))
992 ((assq group groups-alist
)
995 (or (org-element-property :post-affiliated datum
)
996 (org-element-property :begin datum
))
998 "Forbidden combination in header \"%s\": %s, %s"
1000 (cdr (assq group groups-alist
))
1004 (t (push (cons group v
) groups-alist
)
1005 (setf valid-value t
))))
1009 (or (org-element-property :post-affiliated datum
)
1010 (org-element-property :begin datum
))
1011 (format "Unknown value \"%s\" for header \"%s\""
1020 (defvar org-lint--report-mode-map
1021 (let ((map (make-sparse-keymap)))
1022 (set-keymap-parent map tabulated-list-mode-map
)
1023 (define-key map
(kbd "RET") 'org-lint--jump-to-source
)
1024 (define-key map
(kbd "TAB") 'org-lint--show-source
)
1025 (define-key map
(kbd "C-j") 'org-lint--show-source
)
1026 (define-key map
(kbd "h") 'org-lint--hide-checker
)
1027 (define-key map
(kbd "i") 'org-lint--ignore-checker
)
1029 "Local keymap for `org-lint--report-mode' buffers.")
1031 (define-derived-mode org-lint--report-mode tabulated-list-mode
"OrgLint"
1032 "Major mode used to display reports emitted during linting.
1033 \\{org-lint--report-mode-map}"
1034 (setf tabulated-list-format
1037 (< (string-to-number (aref (cadr a
) 0))
1038 (string-to-number (aref (cadr b
) 0))))
1042 (tabulated-list-init-header))
1044 (defun org-lint--generate-reports (buffer checkers
)
1045 "Generate linting report for BUFFER.
1047 CHECKERS is the list of checkers used.
1049 Return an alist (ID [LINE TRUST DESCRIPTION CHECKER]), suitable
1050 for `tabulated-list-printer'."
1051 (with-current-buffer buffer
1053 (goto-char (point-min))
1054 (let ((ast (org-element-parse-buffer))
1058 ;; Insert unique ID for each report. Replace buffer positions
1059 ;; with line numbers.
1067 (goto-char (car report
))
1069 (prog1 (number-to-string
1071 (count-lines last-pos
(point))))
1072 (setf last-pos
(point))))
1074 ;; Insert trust level in generated reports. Also sort them
1075 ;; by buffer position in order to optimize lines computation.
1078 (let ((trust (symbol-name (org-lint-checker-trust c
))))
1081 (list (car report
) trust
(nth 1 report
) c
))
1084 (intern (format "org-lint-%s"
1085 (org-lint-checker-name c
)))
1088 #'car-less-than-car
))))))
1090 (defvar-local org-lint--source-buffer nil
1091 "Source buffer associated to current report buffer.")
1093 (defvar-local org-lint--local-checkers nil
1094 "List of checkers used to build current report.")
1096 (defun org-lint--refresh-reports ()
1097 (setq tabulated-list-entries
1098 (org-lint--generate-reports org-lint--source-buffer
1099 org-lint--local-checkers
))
1100 (tabulated-list-print))
1102 (defun org-lint--current-line ()
1103 "Return current report line, as a number."
1104 (string-to-number (aref (tabulated-list-get-entry) 0)))
1106 (defun org-lint--current-checker (&optional entry
)
1107 "Return current report checker.
1108 When optional argument ENTRY is non-nil, use this entry instead
1110 (aref (if entry
(nth 1 entry
) (tabulated-list-get-entry)) 3))
1112 (defun org-lint--display-reports (source checkers
)
1113 "Display linting reports for buffer SOURCE.
1114 CHECKERS is the list of checkers used."
1115 (let ((buffer (get-buffer-create "*Org Lint*")))
1116 (with-current-buffer buffer
1117 (org-lint--report-mode)
1118 (setf org-lint--source-buffer source
)
1119 (setf org-lint--local-checkers checkers
)
1120 (org-lint--refresh-reports)
1121 (tabulated-list-print)
1122 (add-hook 'tabulated-list-revert-hook
#'org-lint--refresh-reports nil t
))
1123 (pop-to-buffer buffer
)))
1125 (defun org-lint--jump-to-source ()
1126 "Move to source line that generated the report at point."
1128 (let ((l (org-lint--current-line)))
1129 (switch-to-buffer-other-window org-lint--source-buffer
)
1131 (org-show-set-visibility 'local
)
1134 (defun org-lint--show-source ()
1135 "Show source line that generated the report at point."
1137 (let ((buffer (current-buffer)))
1138 (org-lint--jump-to-source)
1139 (switch-to-buffer-other-window buffer
)))
1141 (defun org-lint--hide-checker ()
1142 "Hide all reports from checker that generated the report at point."
1144 (let ((c (org-lint--current-checker)))
1145 (setf tabulated-list-entries
1146 (cl-remove-if (lambda (e) (equal c
(org-lint--current-checker e
)))
1147 tabulated-list-entries
))
1148 (tabulated-list-print)))
1150 (defun org-lint--ignore-checker ()
1151 "Ignore all reports from checker that generated the report at point.
1152 Checker will also be ignored in all subsequent reports."
1154 (setf org-lint--local-checkers
1155 (remove (org-lint--current-checker) org-lint--local-checkers
))
1156 (org-lint--hide-checker))
1162 (defun org-lint (&optional arg
)
1163 "Check current Org buffer for syntax mistakes.
1165 By default, run all checkers. With a `\\[universal-argument]' prefix ARG, \
1167 category of checkers only. With a `\\[universal-argument] \
1168 \\[universal-argument]' prefix, run one precise
1169 checker by its name.
1171 ARG can also be a list of checker names, as symbols, to run."
1173 (unless (derived-mode-p 'org-mode
) (user-error "Not in an Org buffer"))
1174 (when (called-interactively-p 'any
)
1175 (message "Org linting process starting..."))
1178 (`nil org-lint--checkers
)
1182 "Checker category: "
1183 (mapcar #'org-lint-checker-categories org-lint--checkers
)
1187 (assoc-string (org-lint-checker-categories c
) category
))
1188 org-lint--checkers
)))
1191 (let ((name (completing-read
1193 (mapcar #'org-lint-checker-name org-lint--checkers
)
1196 (dolist (c org-lint--checkers
)
1197 (when (string= (org-lint-checker-name c
) name
)
1198 (throw 'exit c
)))))))
1200 (cl-remove-if-not (lambda (c) (memq (org-lint-checker-name c
) arg
))
1201 org-lint--checkers
))
1202 (_ (user-error "Invalid argument `%S' for `org-lint'" arg
)))))
1203 (if (not (called-interactively-p 'any
))
1204 (org-lint--generate-reports (current-buffer) checkers
)
1205 (org-lint--display-reports (current-buffer) checkers
)
1206 (message "Org linting process completed"))))
1210 ;;; org-lint.el ends here