Merge branch 'main' into filtering

# Conflicts:
#	klog/app/cli/args/filter.go
#	klog/app/cli/args/now.go
#	klog/app/cli/args/warn.go
#	klog/service/warning.go

Author: jotaen

klog/app/cli/args/filter.go

@@ -11,31 +11,31 @@ import (
 
 type FilterArgs struct {
 	// Date-related filters:
-	Date   klog.Date     `name:"date" placeholder:"DATE" group:"Filter" help:"Entries at this date. DATE has to be in format YYYY-MM-DD or YYYY/MM/DD. E.g., '2024-01-31' or '2024/01/31'."`
-	Since  klog.Date     `name:"since" placeholder:"DATE" group:"Filter" help:"Entries since this date (inclusive)."`
-	Until  klog.Date     `name:"until" placeholder:"DATE" group:"Filter" help:"Entries until this date (inclusive)."`
-	Period period.Period `name:"period" placeholder:"PERIOD" group:"Filter" help:"Entries within a calendar period. PERIOD has to be in format YYYY, YYYY-MM, YYYY-Www or YYYY-Qq. E.g., '2024', '2024-04', '2022-W21' or '2024-Q1'."`
+	Date   klog.Date     `name:"date" placeholder:"DATE" group:"Filter Flags:" help:"Entries at this date. DATE has to be in format YYYY-MM-DD or YYYY/MM/DD. E.g., '2024-01-31' or '2024/01/31'."`
+	Since  klog.Date     `name:"since" placeholder:"DATE" group:"Filter Flags:" help:"Entries since this date (inclusive)."`
+	Until  klog.Date     `name:"until" placeholder:"DATE" group:"Filter Flags:" help:"Entries until this date (inclusive)."`
+	Period period.Period `name:"period" placeholder:"PERIOD" group:"Filter Flags:" help:"Entries within a calendar period. PERIOD has to be in format YYYY, YYYY-MM, YYYY-Www or YYYY-Qq. E.g., '2024', '2024-04', '2022-W21' or '2024-Q1'."`
 
 	// Filter shortcuts:
 	// The two `XXX` ones are dummy entries just for the help output, they also aren’t available
 	// for tab completion. The other ones are not shown in the help output (because that would be
 	// too verbose then), but they are still available for tab completion.
-	Today       bool `name:"today" group:"Filter" help:"Records at today’s date."`
-	Yesterday   bool `name:"yesterday" group:"Filter" help:"Records at yesterday’s date."`
-	ThisXXX     bool `name:"this-***" group:"Filter" help:"Records of this week/month/quarter/year, e.g. '--this-week' or '--this-quarter'." completion-enabled:"false"`
-	LastXXX     bool `name:"last-***" group:"Filter" help:"Records of last week/month/quarter/year, e.g. '--last-month' or '--last-year'." completion-enabled:"false"`
-	ThisWeek    bool `hidden:"" name:"this-week" group:"Filter" completion-enabled:"true"`
-	LastWeek    bool `hidden:"" name:"last-week" group:"Filter" completion-enabled:"true"`
-	ThisMonth   bool `hidden:"" name:"this-month" group:"Filter" completion-enabled:"true"`
-	LastMonth   bool `hidden:"" name:"last-month" group:"Filter" completion-enabled:"true"`
-	ThisQuarter bool `hidden:"" name:"this-quarter" group:"Filter" completion-enabled:"true"`
-	LastQuarter bool `hidden:"" name:"last-quarter" group:"Filter" completion-enabled:"true"`
-	ThisYear    bool `hidden:"" name:"this-year" group:"Filter" completion-enabled:"true"`
-	LastYear    bool `hidden:"" name:"last-year" group:"Filter" completion-enabled:"true"`
+	Today       bool `name:"today" group:"Filter Flags:" help:"Records at today’s date."`
+	Yesterday   bool `name:"yesterday" group:"Filter Flags:" help:"Records at yesterday’s date."`
+	ThisXXX     bool `name:"this-***" group:"Filter Flags:" help:"Records of this week/month/quarter/year, e.g. '--this-week' or '--this-quarter'." completion-enabled:"false"`
+	LastXXX     bool `name:"last-***" group:"Filter Flags:" help:"Records of last week/month/quarter/year, e.g. '--last-month' or '--last-year'." completion-enabled:"false"`
+	ThisWeek    bool `hidden:"" name:"this-week" group:"Filter Flags:" completion-enabled:"true"`
+	LastWeek    bool `hidden:"" name:"last-week" group:"Filter Flags:" completion-enabled:"true"`
+	ThisMonth   bool `hidden:"" name:"this-month" group:"Filter Flags:" completion-enabled:"true"`
+	LastMonth   bool `hidden:"" name:"last-month" group:"Filter Flags:" completion-enabled:"true"`
+	ThisQuarter bool `hidden:"" name:"this-quarter" group:"Filter Flags:" completion-enabled:"true"`
+	LastQuarter bool `hidden:"" name:"last-quarter" group:"Filter Flags:" completion-enabled:"true"`
+	ThisYear    bool `hidden:"" name:"this-year" group:"Filter Flags:" completion-enabled:"true"`
+	LastYear    bool `hidden:"" name:"last-year" group:"Filter Flags:" completion-enabled:"true"`
 
 	// General filters:
-	Tags   []klog.Tag `name:"tag" placeholder:"TAG" group:"Filter" help:"Entries that match these tags (either in the record summary or the entry summary). You can omit the leading '#'."`
-	Filter string     `name:"filter" placeholder:"EXPR" group:"Filter" help:"Entries that match this filter expression. Run 'klog info --filtering' to learn how expressions works."`
+	Tags   []klog.Tag `name:"tag" placeholder:"TAG" group:"Filter Flags:" help:"Entries that match these tags (either in the record summary or the entry summary). You can omit the leading '#'."`
+	Filter string     `name:"filter" placeholder:"EXPR" group:"Filter Flags:" help:"Entries that match this filter expression. Run 'klog info --filtering' to learn how expressions works."`
 
 	hasPartialRecordsWithShouldTotal bool // Field only for internal use
 }

klog/app/cli/args/warn.go

@@ -13,16 +13,22 @@ type WarnArgs struct {
 
 func (args *WarnArgs) PrintWarnings(ctx app.Context, records []klog.Record, additionalWarnings []service.UsageWarning) {
 	styler, _ := ctx.Serialise()
+	warnings := args.GatherWarnings(ctx, records, additionalWarnings)
+	for _, w := range warnings {
+		ctx.Print(prettify.PrettifyWarning(w, styler))
+	}
+}
+
+func (args *WarnArgs) GatherWarnings(ctx app.Context, records []klog.Record, additionalWarnings []service.UsageWarning) []string {
 	if args.NoWarn {
-		return
+		return nil
 	}
 	disabledCheckers := ctx.Config().NoWarnings.UnwrapOr(service.NewDisabledCheckers())
+	warnings := service.CheckForWarnings(ctx.Now(), records, disabledCheckers)
 	for _, warn := range additionalWarnings {
 		if warn != (service.UsageWarning{}) && !disabledCheckers[warn.Name] {
-			ctx.Print(prettify.PrettifyGeneralWarning(warn.Message, styler))
+			warnings = append(warnings, warn.Message)
 		}
 	}
-	service.CheckForWarnings(func(w service.Warning) {
-		ctx.Print(prettify.PrettifyWarning(w, styler))
-	}, ctx.Now(), records, disabledCheckers)
+	return warnings
 }

klog/app/cli/json.go

@@ -4,23 +4,29 @@ import (
 	"github.com/jotaen/klog/klog/app"
 	"github.com/jotaen/klog/klog/app/cli/args"
 	"github.com/jotaen/klog/klog/parser/json"
+	"github.com/jotaen/klog/klog/service"
 )
 
 type Json struct {
 	Pretty bool `name:"pretty" help:"Pretty-print output."`
 	args.NowArgs
 	args.FilterArgs
 	args.SortArgs
+	args.WarnArgs
 	args.InputFilesArgs
 }
 
 func (opt *Json) Help() string {
 	return `
-The output structure is a JSON object which contains two properties at the top level: 'records' and 'errors'.
-If the file is valid, 'records' is an array containing a JSON object for each record, and 'errors' is 'null'.
-If the file has syntax errors, 'records' is 'null', and 'errors' contains an array of error objects.
+The output structure is a JSON object which contains three properties at the top level: 'records', 'warnings' and 'errors':
 
-The structure of the 'record' and 'error' objects is always uniform and should be self-explanatory.
+- If the file is valid, 'records' is an array containing a JSON object for each record, and 'errors' is 'null'.
+
+- If the file is valid, but contains potential problems, 'warnings' is an array of strings with the respective messages.
+
+- If the file has syntax errors, 'records' and 'warnings' are 'null', and 'errors' contains an array of error objects.
+
+The 'record', 'warnings' and 'error' data structures are always uniform and should be self-explanatory.
 You can best explore it by running the command with the --pretty flag.
 `
 }
@@ -30,7 +36,7 @@ func (opt *Json) Run(ctx app.Context) app.Error {
 	if err != nil {
 		parserErrs, isParserErr := err.(app.ParserErrors)
 		if isParserErr {
-			ctx.Print(json.ToJson(nil, parserErrs.All(), opt.Pretty) + "\n")
+			ctx.Print(json.ToJson(nil, parserErrs.All(), nil, opt.Pretty) + "\n")
 			return nil
 		}
 		return err
@@ -45,6 +51,7 @@ func (opt *Json) Run(ctx app.Context) app.Error {
 		return fErr
 	}
 	records = opt.ApplySort(records)
-	ctx.Print(json.ToJson(records, nil, opt.Pretty) + "\n")
+	warnings := opt.GatherWarnings(ctx, records, []service.UsageWarning{opt.GetWarning()})
+	ctx.Print(json.ToJson(records, nil, warnings, opt.Pretty) + "\n")
 	return nil
 }

klog/app/cli/prettify/prettifier.go

@@ -6,7 +6,6 @@ import (
 	"strings"
 
 	"github.com/jotaen/klog/klog/app"
-	"github.com/jotaen/klog/klog/service"
 	"github.com/jotaen/klog/klog/service/filter"
 	tf "github.com/jotaen/klog/lib/terminalformat"
 )
@@ -81,13 +80,8 @@ func PrettifyFilterError(e filter.ParseError, styler tf.Styler) error {
 	)
 }
 
-// PrettifyWarning formats a warning about a record.
-func PrettifyWarning(w service.Warning, styler tf.Styler) string {
-	return PrettifyGeneralWarning(w.Date().ToString()+": "+w.Warning(), styler)
-}
-
-// PrettifyGeneralWarning formats a general warning message.
-func PrettifyGeneralWarning(message string, styler tf.Styler) string {
+// PrettifyWarning formats a warning message.
+func PrettifyWarning(message string, styler tf.Styler) string {
 	result := ""
 	result += styler.Props(tf.StyleProps{Background: tf.YELLOW, Color: tf.YELLOW}).Format("[")
 	result += styler.Props(tf.StyleProps{Background: tf.YELLOW, Color: tf.TEXT_INVERSE}).Format("WARNING")

klog/parser/json/serialiser.go

@@ -6,27 +6,30 @@ package json
 import (
 	"bytes"
 	"encoding/json"
+	"sort"
+	"strings"
+
 	"github.com/jotaen/klog/klog"
 	"github.com/jotaen/klog/klog/parser"
 	"github.com/jotaen/klog/klog/parser/txt"
 	"github.com/jotaen/klog/klog/service"
-	"sort"
-	"strings"
 )
 
 // ToJson serialises records into their JSON representation. The output
 // structure is RecordView at the top level.
-func ToJson(rs []klog.Record, errs []txt.Error, prettyPrint bool) string {
+func ToJson(rs []klog.Record, errs []txt.Error, warnings []string, prettyPrint bool) string {
 	envelop := func() Envelop {
 		if errs == nil {
 			return Envelop{
-				Records: toRecordViews(rs),
-				Errors:  nil,
+				Records:  toRecordViews(rs),
+				Warnings: warnings,
+				Errors:   nil,
 			}
 		} else {
 			return Envelop{
-				Records: nil,
-				Errors:  toErrorViews(errs),
+				Records:  nil,
+				Warnings: nil,
+				Errors:   toErrorViews(errs),
 			}
 		}
 	}()

klog/parser/json/serialiser_test.go

@@ -1,27 +1,29 @@
 package json
 
 import (
+	"testing"
+
 	"github.com/jotaen/klog/klog"
 	"github.com/jotaen/klog/klog/parser"
 	"github.com/jotaen/klog/klog/parser/txt"
 	"github.com/stretchr/testify/assert"
-	"testing"
 )
 
 func TestSerialiseEmptyRecords(t *testing.T) {
-	json := ToJson([]klog.Record{}, nil, false)
-	assert.Equal(t, `{"records":[],"errors":null}`, json)
+	json := ToJson([]klog.Record{}, nil, nil, false)
+	assert.Equal(t, `{"records":[],"warnings":null,"errors":null}`, json)
 }
 
 func TestSerialiseEmptyArrayIfNoErrors(t *testing.T) {
-	json := ToJson(nil, nil, false)
-	assert.Equal(t, `{"records":[],"errors":null}`, json)
+	json := ToJson(nil, nil, nil, false)
+	assert.Equal(t, `{"records":[],"warnings":null,"errors":null}`, json)
 }
 
 func TestSerialisePrettyPrinted(t *testing.T) {
-	json := ToJson(nil, nil, true)
+	json := ToJson(nil, nil, nil, true)
 	assert.Equal(t, `{
   "records": [],
+  "warnings": null,
   "errors": null
 }`, json)
 }
@@ -30,7 +32,7 @@ func TestSerialiseMinimalRecord(t *testing.T) {
 	json := ToJson(func() []klog.Record {
 		r := klog.NewRecord(klog.Ɀ_Date_(2000, 12, 31))
 		return []klog.Record{r}
-	}(), nil, false)
+	}(), nil, nil, false)
 	assert.Equal(t, `{"records":[{`+
 		`"date":"2000-12-31",`+
 		`"summary":"",`+
@@ -42,7 +44,7 @@ func TestSerialiseMinimalRecord(t *testing.T) {
 		`"diff_mins":0,`+
 		`"tags":[],`+
 		`"entries":[]`+
-		`}],"errors":null}`, json)
+		`}],"warnings":null,"errors":null}`, json)
 }
 
 func TestSerialiseFullBlownRecord(t *testing.T) {
@@ -54,7 +56,7 @@ func TestSerialiseFullBlownRecord(t *testing.T) {
 		r.AddRange(klog.Ɀ_Range_(klog.Ɀ_TimeYesterday_(23, 44), klog.Ɀ_Time_(5, 23)), nil)
 		r.Start(klog.NewOpenRange(klog.Ɀ_TimeTomorrow_(0, 28)), klog.Ɀ_EntrySummary_("Started #todo=nr4", "still on #it"))
 		return []klog.Record{r}
-	}(), nil, false)
+	}(), nil, nil, false)
 	assert.Equal(t, `{"records":[{`+
 		`"date":"2000-12-31",`+
 		`"summary":"Hello #World\nWhat’s up?",`+
@@ -90,16 +92,16 @@ func TestSerialiseFullBlownRecord(t *testing.T) {
 		`"start":"0:28>",`+
 		`"start_mins":1468`+
 		`}]`+
-		`}],"errors":null}`, json)
+		`}],"warnings":null,"errors":null}`, json)
 }
 
 func TestSerialiseParserErrors(t *testing.T) {
 	block, _ := txt.ParseBlock("2018-99-99\n asdf", 6)
 	json := ToJson(nil, []txt.Error{
 		parser.ErrorInvalidDate().New(block, 0, 0, 10),
 		parser.ErrorMalformedSummary().New(block, 1, 3, 5).SetOrigin("/a/b/c/file.klg"),
-	}, false)
-	assert.Equal(t, `{"records":null,"errors":[{`+
+	}, nil, false)
+	assert.Equal(t, `{"records":null,"warnings":null,"errors":[{`+
 		`"line":7,`+
 		`"column":1,`+
 		`"length":10,`+
@@ -115,3 +117,24 @@ func TestSerialiseParserErrors(t *testing.T) {
 		`"file":"/a/b/c/file.klg"`+
 		`}]}`, json)
 }
+
+func TestSerialiseWarnings(t *testing.T) {
+	t.Run("include warnings if records are ok", func(t *testing.T) {
+		json := ToJson(nil, nil, []string{"Caution!", "Beware!"}, false)
+		assert.Equal(t, `{"records":[],"warnings":["Caution!","Beware!"],"errors":null}`, json)
+	})
+	t.Run("ignore warnings if records are not ok", func(t *testing.T) {
+		block, _ := txt.ParseBlock("2018-99-99", 6)
+		json := ToJson(nil, []txt.Error{
+			parser.ErrorInvalidDate().New(block, 0, 0, 10),
+		}, []string{"Caution!", "Beware!"}, false)
+		assert.Equal(t, `{"records":null,"warnings":null,"errors":[{`+
+			`"line":7,`+
+			`"column":1,`+
+			`"length":10,`+
+			`"title":"Invalid date",`+
+			`"details":"Please make sure that the date format is either YYYY-MM-DD or YYYY/MM/DD, and that its value represents a valid day in the calendar.",`+
+			`"file":""`+
+			`}]}`, json)
+	})
+}

klog/parser/json/view.go

@@ -1,10 +1,14 @@
 package json
 
 // Envelop is the top level data structure of the JSON output.
-// It contains two nodes, `records` and `errors`, one of which is always `null`.
+// It contains three nodes:
+// - `records`: is `null` if there are errors
+// - `warnings`: only if applicable and only unless there are errors
+// - `errors`: only unless there are records
 type Envelop struct {
-	Records []RecordView `json:"records"`
-	Errors  []ErrorView  `json:"errors"`
+	Records  []RecordView `json:"records"`
+	Warnings []string     `json:"warnings"`
+	Errors   []ErrorView  `json:"errors"`
 }
 
 // RecordView is the JSON representation of a record.

klog/service/warning.go

@@ -7,12 +7,6 @@ import (
 	"github.com/jotaen/klog/klog"
 )
 
-// Warning contains information for helping locate an issue within the data.
-type Warning struct {
-	date   klog.Date
-	origin checker
-}
-
 // UsageWarning contains information for avoiding potential usage issues.
 type UsageWarning struct {
 	Name    string
@@ -30,16 +24,6 @@ var (
 	}
 )
 
-// Date is the date of the record that the warning refers to.
-func (w Warning) Date() klog.Date {
-	return w.date
-}
-
-// Warning is a short description of the problem.
-func (w Warning) Warning() string {
-	return w.origin.Message()
-}
-
 type checker interface {
 	Warn(klog.Record) klog.Date
 	Message() string
@@ -66,7 +50,7 @@ func NewDisabledCheckers() DisabledCheckers {
 // strict validation, but the main purpose is to help users spot accidental mistakes users
 // might have made. The checks are limited to record-level, because otherwise it would
 // need to make assumptions on how records are organised within or across files.
-func CheckForWarnings(onWarn func(Warning), reference gotime.Time, rs []klog.Record, disabledCheckers DisabledCheckers) {
+func CheckForWarnings(reference gotime.Time, rs []klog.Record, disabledCheckers DisabledCheckers) []string {
 	now := NewDateTimeFromGo(reference)
 	sortedRs := Sort(rs, false)
 	checkers := []checker{
@@ -75,20 +59,19 @@ func CheckForWarnings(onWarn func(Warning), reference gotime.Time, rs []klog.Rec
 		&overlappingTimeRangesChecker{},
 		&moreThan24HoursChecker{},
 	}
+	var warnings []string
 	for _, r := range sortedRs {
 		for _, c := range checkers {
 			if disabledCheckers[c.Name()] {
 				continue
 			}
 			d := c.Warn(r)
 			if d != nil {
-				onWarn(Warning{
-					date:   d,
-					origin: c,
-				})
+				warnings = append(warnings, d.ToString()+": "+c.Message())
 			}
 		}
 	}
+	return warnings
 }
 
 type unclosedOpenRangeChecker struct {