ARCHITECTURE.md names missing identifiers and describes replaced behavior

未关闭 适合新手
  • 哪里不对？
#327 0 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

维护者通常 1 天内回复

还没有人认领这个 Issue。

评估

难度
2/5
预计耗时
1-3 小时
新手友好度
85/100
Issue 类型
文档
描述清晰度
描述清楚
活跃度
活跃
技术栈
go
领域
documentation

调研方向

从 docs/ARCHITECTURE.md 开始，将每一处引用的行与其所指的代码逐一核对：main_wordlist.go（prepareWordlist）、main.go（validateArgs，约第 211 行及 283-301 行）、internal/dns/resolver.go、internal/dns/cname.go、internal/output/writer.go（writeJSONElement）、internal/validate/validate.go、internal/scan/runner.go、main_ct.go 和 main_config.go。修正过时的标识符、-w 的要求、关于 JSON 缓冲的说法、DNS 服务器的写法、EventDone 的行为以及 -dry-run 条目。当 issue 清单中的每一项都已修正，且文件列表包含 cname.go 时，即完成。

由索引模型根据 Issue 内容生成。

描述

area: docs documentation good first issue severity: low

Summary

Ten statements in docs/ARCHITECTURE.md contradict the code: two function names that no longer exist, -w described as required, JSON output described as buffered, and a scan described as able to end without EventDone.

Where

  • docs/ARCHITECTURE.md:66
  • docs/ARCHITECTURE.md:124
  • docs/ARCHITECTURE.md:158
  • docs/ARCHITECTURE.md:194
  • docs/ARCHITECTURE.md:197
  • docs/ARCHITECTURE.md:250
  • docs/ARCHITECTURE.md:253
  • docs/ARCHITECTURE.md:268
  • docs/ARCHITECTURE.md:331
  • docs/ARCHITECTURE.md:343
  • main_wordlist.go:56
  • main.go:211
  • main.go:283-301
  • internal/dns/resolver.go:284-290
  • internal/dns/resolver.go:329-332
  • internal/dns/cname.go:49-62
  • internal/output/writer.go:255
  • internal/validate/validate.go:47-67
  • internal/scan/runner.go:590-596
  • main_ct.go:28
  • main_config.go:39

Details

Each item below contradicts the code at d0c56f0:

  • :66 main_wordlist.go - readWordlist. No readWordlist exists; the file defines prepareWordlist (main_wordlist.go:56) and the wordlistPaths flag value.
  • :124 "validateFlags, which checks that -w and a target are present", and :250 "When -w or a target ... is missing ... exits with status 2". -w is optional (main.go:211, "omitted: the bundled top-5000 list"); validateArgs checks only the domain or -dL (main.go:283-301).
  • :158 "one lookup per requested record type (... CNAME via LookupCNAME ...)". CNAME goes through the package's own lookupCNAME, one query (cname.go:49-62; resolver.go:286 "not Go's LookupCNAME, which also sends A and AAAA (#249)"), and the types are looked up at the same time (resolver.go:329-332, #250). Line 160 of the same document already says the opposite about CNAME.
  • :194 "In json format results are buffered and written as a single array by Finish" and :197 "Finish - writes the buffered JSON array". The array is streamed element by element (writeJSONElement, writer.go:255, #181; CHANGELOG.md:47).
  • :253 "The DNS server must be a valid ip:port with an IP host". tls://host[:port] and https://host/path are accepted, and their host may be a name (validate.go:47-67). Line 125 of the same document says so.
  • :268 "a failed preflight or an inconclusive wildcard check ... emits EventError and ends the scan without EventDone". Every scan ends with exactly one EventDone, with Stopped set when it ended before the candidates (runner.go:590-596, #99).
  • :331 "withCTEntries appends those not already in the wordlist". No such function; the passive names are gathered by passiveNames (main_ct.go:28) and merged by passive.Merge.
  • :343 lists the flags never taken from defaults as -tui, -version, -print-config, -resume, -h; dry-run is in noDefaultFlags too (main_config.go:39), as README.md:417 and docs/cli.md:44 say.
  • The file list (:75-84) has no entry for internal/dns/cname.go.

Impact

A contributor searching for readWordlist or withCTEntries finds nothing, and one who writes a scan.Run consumer from section 4.3 will treat a missing EventDone as a possible outcome, or budget five queries for -type A,AAAA,CNAME instead of three.

Suggested fix

Correct the nine items in place: rename the two functions, drop "-w and" from 2.1 and 4.1, rewrite the Lookups bullet (own lookupCNAME, concurrent types), say JSON is streamed and Finish closes the array, list the three resolver forms in 4.1, say EventDone follows with Stopped set in 4.3, add -dry-run to 5.8 and cname.go to the file list.

Acceptance criteria

  • Each checklist item under Details is corrected

Getting started

  • Relevant files: docs/ARCHITECTURE.md, main_wordlist.go, main.go, internal/dns/resolver.go
  • How to run tests: make test (or go test ./...). Tests must stay hermetic: use -simulate, -simulate-zone or the local DNS test server, never a live domain.
  • Related docs: docs/DEVELOPER_GUIDE.md, docs/ARCHITECTURE.md

Filed by repo-audit/full-audit at d0c56f0. Severity: low. Effort: S. audit-key: documentation|docs/ARCHITECTURE.md|stale-identifiers

主要语言
Go
星标
1
派生
1
平均合并
6 小时 42 分钟
30 天内合并 PR
7

环境准备

在 Codespaces 中打开

在浏览器里用你自己的 GitHub 账号启动这个项目的开发容器。

从这里开始

  1. 先读完整个 Issue，再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库，在一个分支上完成修改。
  4. 提交 Pull Request，并在描述里引用这个 Issue 编号。

TMHSDigital/subenum 的其他 Issue

查看 TMHSDigital/subenum 的全部 Issue

相似的 Issue

更多 Go Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。